Observability

Message timeline

In production you want a timeline view for every message:

submitted → accepted → queued → routed → deferred/throttled → retried → delivered/bounced/complained

The goal isn't pretty dashboards — it's being able to answer hard questions quickly:

• "Did we send it?"
• "If yes, when and with what payload?"
• "What did the provider do with it?"
• "If it failed, is it safe to retry?"
• "Can support reproduce this with a request ID?"

What to capture (minimum viable)

At minimum, store these identifiers in your own logs and database:

• Your internal business ID (order_id, invoice_id, etc.)
• transmission_id (returned by SendLib when you submit a transmission)
• message_id (when available in events/webhooks)
• X-Request-ID (response header when present)
• Recipient email (or a hashed form if you need privacy)

This is enough to correlate a customer support ticket to an API call and to downstream outcomes.

Recommended pattern: metadata tagging

When you create a transmission, include metadata that lets you join events back to your own objects.

{
  "recipients": [{"email": "user@example.com"}],
  "content": {"subject": "Receipt", "text": "Thanks"},
  "meta": {
    "order_id": "1042",
    "customer_id": "789",
    "environment": "prod",
    "tags": ["receipt", "billing"]
  }
}

Webhooks vs events (use both)

• Webhooks: real-time stream, low latency. Use them to drive product behavior and automation (suppression, user notifications, workflows).
• Events API: queryable backfill for audits, debugging, reconciliation, and "what happened yesterday?" investigations.

If you rely only on webhooks, you eventually hit gaps (downtime, signature validation bugs, queue backpressure). If you rely only on events, you build slow product behavior and hammer the API.

Support playbook

When debugging a customer report, your best workflow is:

1. Search by internal business ID.
2. Find the transmission_id and X-Request-ID from the originating API call.
3. Pull webhook events by message_id / recipient.
4. If there are missing webhook events, backfill via Events API with a time-bounded query.

Next

• Real-time outcomes: Webhooks
• Backfills and audits: Events
• Debug common issues: Troubleshooting