Observability and alerting
Store three identifiers, from the start
| Identifier | Where | Ties to |
|---|---|---|
request_id |
response header and error body | our logs, support |
message_id |
send response | delivery events, the message explorer |
Idempotency-Key |
yours | whether a retry was a replay |
Store all three against your own row at send time. Retrofitting them means the incident you are investigating is the one where you do not have them.
See Logging without leaking for what to keep out of those logs.
What to pull, and how often
| Endpoint | Use it for | Cadence |
|---|---|---|
GET /v1/usage |
pacing, quota headroom | before a batch, or every few minutes |
GET /v1/messages/stats |
delivered against bounced | a dashboard, every few minutes |
GET /v1/reputation |
whether your cap was lowered | every few minutes, and on any 429 |
GET /v1/events |
what we tried to tell you | on demand, when a handler looks wrong |
None of these is rate-limited today, which is not a reason to poll hard. See Every limit, in one place.
Prefer webhooks for outcomes. Polling for delivery status when an event would have told you is the most common unnecessary load in an integration.
Metrics worth having
Four, and the fourth is the one people miss:
Send attempt rate and outcome split. delivered, bounced, deferred,
complaint, as a rate rather than a total.
Bounce rate as a percentage, not a count. A count rises with volume and tells you nothing; the percentage is what the reputation engine acts on, and what you want to see move before it does.
Queue depth and age in your own system. Our queue is not visible to you; yours is, and a growing oldest-item age is the earliest signal that sending has stalled.
Webhook handler lag. The gap between an event’s timestamp and when you processed it. If this grows, your view of delivery is stale and every decision downstream is made on old data, which looks like a data problem rather than a queue problem.
What to alert on
| Alert | Why |
|---|---|
| Bounce rate over your own threshold | before the platform’s, so you act first |
tenant.throttled webhook |
your cap was lowered and you did not do it |
tenant.usage_threshold at 80% |
buy or upgrade with time to spare |
| Dead-letter rate | a broken integration, as opposed to a bad address |
| Webhook handler failures | you are losing outcomes silently |
Subscribe to the platform events
Two carry information you cannot easily derive:
tenant.throttled, because a429from a reputation throttle is indistinguishable from an ordinary cap without ittenant.usage_threshold, at 80% and 100% of the monthly allowance
Both are workspace-level rather than per message, and both are things you would otherwise discover by noticing sends had stopped.