The states a message goes through
What each state means, what caused it, and what to do next.
A message moves through states, and not all of them are a problem. This page is what each one means and what to do with it.
The normal sequence
queued → accepted → delivered
Queued. We accepted the request, signed the message and put it in the queue. It has not left yet.
Accepted. The relay took it and accepted responsibility for delivering it.
It is the state the API returns with its 202.
Delivered. The recipient's server accepted it. It is the best signal there is, but note what it does not say: it does not say the person saw it, nor that it is not in the spam folder. It says the server accepted it.
The states that ask something of you
Deferred. The receiver said "not now, try later". It is a temporary error, a
4xx in SMTP. It happens with a full mailbox, a rate limit on their side, or a
busy server. Do nothing: we try again, with growing gaps, for hours. Most
deferrals end in delivery.
Bounced. The receiver refused for good, with a 5xx. In most cases the
address does not exist. The address goes onto this account's suppression list
automatically and is not contacted again. What you have to do is on your side:
mark the contact as invalid, so you do not keep trying with it from some other
system.
Complained. The person pressed "this is spam". It reaches us through the provider's feedback channel, and the address is suppressed across the whole platform, not only for this account. It is the most expensive event there is: a complaint rate above 0.1% drags delivery down for everybody sharing the IP. It is always worth understanding what was sent.
Suppressed. We did not even try: the address was already on the suppression list when you asked us to send. It is not a failure, it is the system saving you a bounce.
Failed. We gave up after several attempts, or something went wrong on our side. The SMTP code in the message's timeline is worth reading.
What to do with each
| State | Retry? | What to do |
|---|---|---|
queued, accepted |
No | Wait. |
delivered |
No | Nothing. |
deferred |
No | Nothing, we retry. |
bounced |
No | Mark the contact as invalid. |
complained |
Never | Understand what was sent, and to whom. |
suppressed |
No | Clear that address from your list. |
failed |
Maybe | Read the SMTP code first. |
The short rule: never retry a send to a bounced address. Every attempt at an address that does not exist counts against the IP's reputation, and that reputation is shared with every other client.
Where to see it
In the panel, under Messages, each row carries the state and clicking it opens the full timeline: when it was accepted, which server it left through, and what the receiver answered, with the error text as it came.
Over the API, GET /v1/messages/{id} returns the same, and GET /v1/events
returns the whole stream. If you would rather not poll, register an endpoint in
Webhooks.
Accepted is not delivered
Worth repeating. The API's 202 means accepted. If your application shows
"email sent" at that moment, it is promising something that has not happened
yet, and sometimes does not happen at all.