mailnix Docs
    mailnix / REST: traces

    API reference

    REST: traces

    Every send gets a trace_id and a trace: the full event timeline from request to terminal state, across retries and failovers.

    Endpoints

    • GET /v1/traces/{trace_id}: the authenticated view. Full timeline, recipient addresses, provider transcripts.
    • GET /share/traces/{trace_id}: a public, read-only, redacted view of the same trace, safe to paste into a bug report or hand to a teammate without credentials.

    The status state machine

    pending -> queued -> sent -> delivered   (terminal)
                          -> bounced     (terminal)
                          -> complained  (terminal)
                          -> failed -> queued ...  (retry)
pending -> validation_failed             (terminal)
pending -> suppressed                    (terminal)

    Event types on the timeline

    request_received, validation_failed, suppressed, routing_decision, provider_attempt, provider_response, failover_triggered, provider_event_delivery, provider_event_bounce, provider_event_complaint, provider_event_open, provider_event_click, inbound_received, manual_resend.

    Traces can also receive late annotations: auto_suppressed records that a bounce or complaint arrived after delivery and the recipient was auto-added to the suppression list (where the operator has enabled automatic suppression for the org). The terminal status does not change retroactively.

    Retention

    Trace retention follows your plan (7 days inside the free quota, up to unlimited on Enterprise; see Quotas). The concepts page Traces covers how to read a timeline; the full request/response schemas are in the OpenAPI spec.