Temporary and permanent failures
A message you send is accepted with 202 and then has a life of its own. This
page is the vocabulary for the rest of that life.
The five states
GET /v1/messages/{id} reports one of these.
| Status | Meaning |
|---|---|
queued |
Accepted by us, not yet handed to the mail server. |
delivered |
The receiving server accepted it. |
bounced |
Permanently rejected. The address is now suppressed. |
deferred |
Our submission failed and automatic retries are finished or were never safe. See Retry strategies. |
unconfirmed |
Handed over, and we never found out what happened. |
A scheduled send also reads as scheduled until its time arrives.
Temporary against permanent
The split is the SMTP response class, and it is made at the point of failure:
- 5xx is permanent. The server is saying this will never work: no such
mailbox, domain refuses you, message rejected. The outcome is
bouncedand the recipient is added to your suppression list. - 4xx is temporary. The server is saying not now: greylisted, over quota, rate limited, busy. A temporary failure is not a bounce, is not counted against your bounce rate, and does not suppress anybody.
- A connection-level error with no SMTP code at all is treated as temporary, which is the safe reading.
unconfirmed is an honest answer, not a failure
This is the state people misread, so it is worth being exact.
unconfirmed means: the mail server accepted the message, no delivery or
bounce event ever reached us, 24 hours passed, and the message is no longer
sitting in the server’s queue being retried.
At that point the outcome is genuinely unknowable. The server no longer holds
the message and nothing else recorded whether it arrived. The platform marks
it unconfirmed and never guesses, because the two available guesses are
both harmful: calling it delivered inflates your stats, and calling it bounced
would suppress a recipient who may have received the message perfectly well.
Things unconfirmed does not mean:
- it does not mean the message failed;
- it does not suppress the recipient;
- it does not count against your bounce rate;
- it does not mean the message is still being attempted. A message the server is still working on is deliberately excluded, so a healthy send is never written off while the queue is retrying it.
A few are normal; a lot is a signal. A healthy integration sees the occasional one, where a confirmation genuinely went missing. If most of your recent sends are ending up here, that is a reporting problem worth raising with support rather than a deliverability problem, because the mail most likely arrived.
Either way, read your stats as delivered-versus-bounced among messages that reached a decided outcome, and leave the undecided ones out of both sides. Monitoring has the arithmetic.
Mapping to webhooks
| Event | Fires on |
|---|---|
delivery.delivered |
The receiving server accepted it |
delivery.failed |
Submission failed |
delivery.dsn-perm-fail |
A permanent failure report, the one that bounces and suppresses |
delivery.dsn-temp-fail |
A temporary failure report, informational |
There is no event for unconfirmed, because nothing happens at that moment
except a timer expiring. If you need to know, poll
GET /v1/messages/{id} or read the aggregate counts.
See Webhook event types.
What to do with each
| Status | Your move |
|---|---|
bounced |
Nothing to retry. Remove the address at source; it is already suppressed. |
deferred |
Automatic retries are done. Investigate, then retry explicitly. |
unconfirmed |
Nothing. Resending risks a duplicate for a message that very likely arrived. |
queued for a long time |
Check the rate and warm-up caps, then contact support. |