Reference
Message statuses
Every message carries one of 14 statuses. Each says where the message is, whether its story is over, and which webhook reports it.
Tested with resend@6.30.0
Last reviewed
On this page (5)
POST /emails; the message is queued, handed to Postal, sent and delivered, and your webhook hears about it. Side routes lead to Delayed and Bounced. Inbound: mail arrives at Letterpier’s MX, is received, and your webhook tells your app.Each status has one badge everywhere: in the dashboard, in these docs and on the website. Dashed: the story isn’t over. Solid: settled. Hatched: not real mail.
| Status | What it means | Webhook event |
|---|---|---|
| Not settled yet | ||
| Queued | Accepted by the API and waiting for the worker. | None |
| Scheduled | Waiting for its send time, up to 30 days ahead. It can be rescheduled or cancelled until then. | None |
| Submitting | The worker is handing it to Postal, Letterpier’s mail server. | None |
| Sent | Postal accepted it and is delivering it. | email.sent |
| Delayed | The receiving server deferred it. Postal keeps retrying. | email.delivery_delayed |
| Unknown | The hand-off to Postal was interrupted, so the outcome isn’t confirmed. Letterpier never resends on its own; use Check Postal acceptance. | None yet |
| Settled | ||
| Delivered | The recipient’s mail server accepted it. That isn’t a promise of the inbox, and a bounce can still follow. | email.delivered |
| Held | Not delivered. Letterpier held it before submission (for example, the domain’s DNS check is older than 24 hours), or Postal held it. Webhooks report email.. | email.failed |
| Bounced | The receiving side refused it. The address was added to this project’s suppression list. | email.bounced |
| Failed | Delivery failed permanently. The address was added to this project’s suppression list, and the log shows the last error. | email.failed |
| Suppressed | Not sent, because a recipient is on this project’s suppression list. Webhooks report email.. | email.failed |
| Cancelled | Cancelled before it was submitted. | None |
| Received | Inbound mail for an address on one of your verified domains. | email.received |
| Not real mail | ||
| Sandbox | Captured by a sandbox key. Never delivered. | email.sent |
Message statuses, grouped by whether the story is over
Not settled yet
- Queued
- What it means
- Accepted by the API and waiting for the worker.
- Webhook event
- None
- Scheduled
- What it means
- Waiting for its send time, up to 30 days ahead. It can be rescheduled or cancelled until then.
- Webhook event
- None
- Submitting
- What it means
- The worker is handing it to Postal, Letterpier’s mail server.
- Webhook event
- None
- Sent
- What it means
- Postal accepted it and is delivering it.
- Webhook event
email.sent
- Delayed
- What it means
- The receiving server deferred it. Postal keeps retrying.
- Webhook event
email.delivery_delayed
- Unknown
- What it means
- The hand-off to Postal was interrupted, so the outcome isn’t confirmed. Letterpier never resends on its own; use Check Postal acceptance.
- Webhook event
- None yet
Settled
- Delivered
- What it means
- The recipient’s mail server accepted it. That isn’t a promise of the inbox, and a bounce can still follow.
- Webhook event
email.delivered
- Held
- What it means
- Not delivered. Letterpier held it before submission (for example, the domain’s DNS check is older than 24 hours), or Postal held it. Webhooks report
email..failed - Webhook event
email.failed
- Bounced
- What it means
- The receiving side refused it. The address was added to this project’s suppression list.
- Webhook event
email.bounced
- Failed
- What it means
- Delivery failed permanently. The address was added to this project’s suppression list, and the log shows the last error.
- Webhook event
email.failed
- Suppressed
- What it means
- Not sent, because a recipient is on this project’s suppression list. Webhooks report
email..failed - Webhook event
email.failed
- Cancelled
- What it means
- Cancelled before it was submitted.
- Webhook event
- None
- Received
- What it means
- Inbound mail for an address on one of your verified domains.
- Webhook event
email.received
Not real mail
- Sandbox
- What it means
- Captured by a sandbox key. Never delivered.
- Webhook event
email.sent
mail.emails.get(id) and mail.emails.list() report the status as last_event, in lower case. Sandbox messages report sent together with sandbox: true.
| Status | last_event |
|---|---|
| Queued | queued |
| Scheduled | scheduled |
| Submitting | submitting |
| Sent | sent |
| Delivered | delivered |
| Delayed | delayed |
| Unknown | unknown |
| Held | held |
| Bounced | bounced |
| Failed | failed |
| Suppressed | suppressed |
| Cancelled | cancelled |
| Received | received |
| Sandbox | sent |
Status and last_event
- Queued
- last_event
queued
- Scheduled
- last_event
scheduled
- Submitting
- last_event
submitting
- Sent
- last_event
sent
- Delivered
- last_event
delivered
- Delayed
- last_event
delayed
- Unknown
- last_event
unknown
- Held
- last_event
held
- Bounced
- last_event
bounced
- Failed
- last_event
failed
- Suppressed
- last_event
suppressed
- Cancelled
- last_event
cancelled
- Received
- last_event
received
- Sandbox
- last_event
sent
Differs from Resend
Besides delivery states,
last_event includes Letterpier’s queue states (queued, submitting, unknown, held, suppressed). A deferred message reports delayed, not delivery_delayed, and a cancelled one cancelled, not canceled.Unknown means the hand-off to Postal was interrupted, for example by a timeout, so nobody knows yet whether Postal accepted the message. Sending it again could deliver it twice, so Letterpier never resends it on its own.
Check Postal acceptance on the message looks it up in Postal without sending anything:
- If Postal holds the message for every recipient, it becomes Sent (then follows its delivery results) and your webhook receives
email.sent. - If it doesn’t, nothing changes and nothing is resent. Someone has to look at Postal before deciding whether a new message is safe.
When delivery fails permanently (Bounced or Failed), the recipient’s address joins the project’s suppression list. Each project has its own list.
- A live send that includes a suppressed address is refused with 403
restricted_api_key. - If an address is suppressed after a message was queued, that message becomes Suppressed and your webhook receives
email.failed. - Remove a suppression in the dashboard only after you’ve fixed the cause, such as a mistyped address.