Delivery activity & troubleshooting
Understand what each state means and choose the right recovery action.
Follow a message
GET /v1/notifications/:id adds the durable event timeline. Lists support status, category, channel=email or channel=whatsapp, limit, and cursor filters. Omit channel for both. Match your application request to the returned message ID and request ID.
| Field / scope | Description | Requirement / access |
|---|---|---|
queued / sending | Accepted work waiting or being submitted | In progress |
sent | Provider accepted the message | Not proof of inbox delivery |
delivered | Provider reported delivery | Destination server accepted |
bounced / complained | Provider feedback indicates a recipient issue | Investigate suppression |
failed / suppressed / cancelled | Message did not proceed normally | Inspect its timeline |
unknown | Submission outcome is ambiguous | Do not blindly resend |
Safely retry application requests
After a timeout accepting a request, retry the identical payload and idempotency key. After a known rejection, fix its cause. For an unknown provider outcome, investigate the timeline and provider feedback; a new key can create a duplicate email.
Read aggregate metrics
GET /v1/overview with metrics:read accepts UTC ISO from/to timestamps, an inclusive start and exclusive end. Metrics are send cohorts grouped by notification creation time; delivery may arrive later. The dashboard shows activity and allowance usage separately.
Common integration errors
401: missing, revoked, or invalid key. 403: scope, tenant, approval, or role restriction. 400: invalid fields, missing variables, or unverified sender. 409: conflicting idempotency or resource state. 429: rate limit. 5xx: temporary service problem; use bounded backoff and preserve your idempotency key.