Delivery status
Interpret asynchronous sending results without confusing queue acceptance with final recipient delivery.
Read message status
GET /api/v1/outbound-messages returns recent organization messages newest first. GET /api/v1/outbound-messages/{id} returns one message, its recipients, and state-change events. Use a read or read_write token.
The authenticated Console provides the same customer-facing history for manual inspection.
Message and recipient states
| State | Meaning | Final? |
|---|---|---|
pending | The accepted message is waiting to be processed. | No |
sending | A delivery attempt is in progress. | No |
retry_ready | A previous processing attempt will be retried. | No |
smtp_accepted | The SMTP server accepted the message for onward delivery. | No |
deferred | Recipient delivery is temporarily delayed and may be attempted again. | No |
delivered | The destination accepted delivery for this recipient. | Yes |
bounced | The destination permanently rejected this recipient. | Yes |
expired | Temporary delivery attempts ended without acceptance. | Yes |
failed | Processing failed before a later recipient outcome was available. | Yes |
Multiple recipients
A message can have different outcomes for different recipients. Inspect every recipient rather than deriving success from the message-level queue state. Bcc recipients appear in authenticated delivery data but are not added to visible message headers.
Polling safely
- Keep the outbound message ID returned by the send request.
- Poll the detail endpoint with increasing intervals rather than continuously listing all messages.
- Stop when every recipient reaches a final state or when your own business timeout expires.
- Do not resend merely because a final state has not appeared yet. Retrying a send is a separate operation and requires the original idempotency key.
Diagnostics and privacy
Use recipient events and diagnostics to investigate failures, but do not expose addresses or delivery responses to unauthorized users or place them in public logs. A successful remote acceptance does not guarantee that a recipient will read the message or that later filtering will not occur.