Reference
Statuses & events
Every message moves through a series of events. Its status is the furthest stage it has reached.
Furthest stage reached
Each message (one per recipient) records an event for every step: queued, sent, delivered, opened, clicked and so on. The message status is not simply the latest event but the furthest stage reached along the happy path. For example, a message that was delivered, then clicked, and later opened again stays CLICKED; a late DELIVERED notification arriving after an OPENED event does not move it back.
Problem outcomes — bounces, complaints, blocks and failures — are reported as the status, so a message that hard-bounced is shown as HARD_BOUNCE. Opens and clicks are still counted separately (the portal shows totals per message).
Email statuses
| Status | Meaning |
|---|---|
| QUEUED | Accepted by the API or SMTP relay and waiting to be sent. |
| SENT | Handed over to the mail infrastructure (Amazon SES). |
| DELIVERED | The recipient's mail server accepted the message. |
| OPENED | The recipient opened the email (tracking pixel loaded). May be affected by privacy features such as Apple Mail Privacy Protection. |
| CLICKED | The recipient clicked a tracked link. |
| SOFT_BOUNCE | Temporary delivery failure (mailbox full, server unavailable…). |
| HARD_BOUNCE | Permanent delivery failure (address does not exist). The address is added to the suppression list. |
| COMPLAINT | The recipient marked the message as spam. The address is suppressed. |
| BLOCKED | Not sent because the recipient is on the suppression list (earlier hard bounce, complaint or unsubscribe). |
| FAILED | Permanent send or render error (for example a template that fails to render with the given params). |
Email events
Besides the status-changing events above, these events are recorded on a message:
| Event | Meaning |
|---|---|
| UNSUBSCRIBED | The recipient used the {{ unsubscribe }} link. Future sends to the address are blocked. |
| OPENED / CLICKED | Recorded on every open and click, with the user agent and, for clicks, the URL. |
| SOFT_BOUNCE / HARD_BOUNCE | Include a diagnostic message and bounce type from the receiving server. |
Where to see events
WhatsApp statuses
| Status | Meaning |
|---|---|
| QUEUED | Accepted by SnappyMails and waiting to be sent to WhatsApp. |
| SENT | Accepted by WhatsApp (a wa_message_id is assigned). |
| DELIVERED | Delivered to the customer's device. |
| READ | The customer opened the message (only when they have read receipts enabled). |
| FAILED | WhatsApp rejected or could not deliver the message; see the error object. |
| RECEIVED | An inbound message from the customer. Opens or refreshes the 24-hour service window. |
WhatsApp statuses follow the same furthest-stage rule: a READ message stays READ even if a delivery receipt arrives afterwards. Poll GET /v1/whatsapp/messages/{messageId} to follow a message.
Good to know
- Timestamps are RFC 3339 in UTC.
- Statuses are recorded per recipient; a message sent to three addresses has three independent statuses.
- Open tracking is approximate; prefer clicks or delivery for critical decisions.
- To be notified instead of polling, subscribe to these events with webhooks.