Skip to content
Invitation-only alpha. Features and limits may change as we learn from testing.

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.

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
└─► suppressed

email.delivery_delayed is not a step on either track: the server reported a delay and keeps trying, so the outcome stays pending.

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.
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.

  • 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} returns reason with code, category and retry.
  • Webhooks: data.reason carries 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.

  • ?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 429 names its limit in error.reason. Wait for Retry-After when it is present, then repeat with the same key. Without Retry-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.