mailnix Docs
    mailnix / Traces

    Core concepts

    Traces

    One unified pipeline record per logical send. Public-shareable UUID. Survives a provider swap.

    What's a trace

    A trace is the unified record of one logical send. Identified by a UUIDv4 trace_id that is public-shareable. Open the trace and you see the routing decision, the provider attempt, the SMTP response code, and every webhook event afterwards, in order, with timestamps.

    Status state machine

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

    Trace timelines may also receive late-arriving annotations. The most common is auto_suppressed: the recipient landed on the suppression list after this send completed. The original trace's terminal status stays whatever it was at delivery time; the annotation is purely informational.

    Trace event types (the canonical enum)

    • 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

    Sharing a trace URL

    Two views per trace:

    • GET /v1/traces/{trace_id}: the full record, auth required.
    • GET /share/traces/{trace_id}: the public read-only view, redacted of PII. Safe to hand to a customer or an AI assistant.

    The trace ID survives a provider swap. If you re-route a destination from SES to Postmark, the trace history of past sends through SES still resolves; the ID is owned by mailnix, not the provider.