Handling errors and states
Two questions matter when something goes wrong: what happened, and is it safe to try again. weneed.email answers both with a reason code, a category and a retry rule. The same codes appear in Control, in the API and in webhooks.
Two separate tracks
Section titled “Two separate tracks”Every message has a submission state (what weneed.email did with it) and a recipient outcome (what the recipient’s mail server reported). They change independently, and neither proves inbox placement.
Submission state
accepted ─► queued ─► dispatching ─► submitted │ ▲ │ │ └─ retry_wait ◄─┤ the server asked to try later ▼ ├─► submission_unknown answer lost; never resent held └─► rejected won't be retried │ queued, held or retry_wait can also end as: expired · cancelled · suppressed
Recipient outcome
pending ─► delivered_to_server ─► (a later bounce report can still arrive) ├─► bounced ├─► delivery_unknown └─► suppressedemail.delivery_delayed is not a step on either track: the server reported a delay and keeps
trying, so the outcome stays pending.
Categories
Section titled “Categories”Every reason code has one category. It tells you who acts next.
| Category | Meaning | Do |
|---|---|---|
wait |
weneed.email or the recipient’s server is still working on it. | Nothing yet. Watch the message or its webhooks. |
fix |
Something on your side needs changing, such as the address, the content or a setting. | Fix it, then send a new message if it is still needed. |
contact_support |
Only weneed can resolve it, for example a hold. | Write to support with the message ID. |
none |
Nothing is wrong. | Nothing. |
Retry rules
Section titled “Retry rules”| Rule | Meaning |
|---|---|
safe_same_key |
Repeat the same request with the same Idempotency-Key. You get the original result, never a second message. |
do_not_resend |
Don’t send the message again. It may already have arrived, or it may still be sent once released. A copy could reach the recipient twice. |
not_applicable |
There is nothing to repeat. |
API errors use their own three rules: safe_same_key, after_change (fix the request first) and
never (repeating can’t succeed). See API errors.
Where to find the reason
Section titled “Where to find the reason”- Control: the message page shows Reason for this status, and the trace shows the reason for each hold, retry and attempt.
- API:
GET /v1/emails/{id}returnsreasonwithcode,categoryandretry. - Webhooks:
data.reasoncarries the same three fields, frozen at the moment of the event.
Look up any code under Reason codes. An unknown code is never hidden:
treat it as contact_support and do_not_resend.
Rules that always hold
Section titled “Rules that always hold”- ?Unknown means unknown. Never resend a message whose outcome is unknown; wait for a delivery report or contact support.
- A webhook is never a reason to resend an email.
- A
429names its limit inerror.reason. Wait forRetry-Afterwhen it is present, then repeat with the same key. WithoutRetry-After, waiting won’t help. - A permanent bounce blocks the address for your whole workspace. Fix the address in your app; don’t work around the block. See Bounces.