Reason codes
These codes appear in Control, in GET /v1/emails/{id} as reason.code, in attempts and in webhook data.reason. Each has a category and a retry rule; see Handling errors and states.
States and attempts
Section titled “States and attempts”Why a message changed state, or how a sending attempt ended.
| Code | What it means | What to do | Next | Retry |
|---|---|---|---|---|
adapter_exception |
Outcome unknown: sending error. The hand-over may have succeeded, but we could not confirm it. It may already have been delivered. | Do not resend. Wait for delivery evidence or contact support. | Wait | Do not resend |
archive_unavailable |
Preparing the message failed. We could not store the signed copy of this message, so nothing was sent. | No action needed. It is retried until it expires. | Wait | — |
attempt_already_submitted |
Repeat hand-over blocked. A safety check stopped this message before it was handed over. | Contact support with the message ID. Do not send it again under another sender. | Support | Do not resend |
attempt_identity_mismatch |
Sending attempt did not match. A safety check stopped this message before it was handed over. | Contact support with the message ID. Do not send it again under another sender. | Support | Do not resend |
authorization_changed |
Held: authorization changed. Sending permission changed between queueing and sending. | Check the project home for current issues, then contact support to release or cancel it. | Support | Do not resend |
binding_mismatch |
Sending route does not match. A safety check stopped this message before it was handed over. | Contact support with the message ID. Do not send it again under another sender. | Support | Do not resend |
cancelled_before_transport |
Cancelled before sending. The sending attempt stopped before contacting the relay. | No email was sent by this attempt. | Nothing | — |
dispatch_not_authorized |
Held: sending not authorized. At the moment of sending, this sender was no longer authorized. | Check the project home for current issues, then contact support to release or cancel it. | Support | Do not resend |
expiry_passed |
Expired before sending. The message’s expiry time passed before it could be sent. It was not sent. | Send a new message if it is still needed. It is not a duplicate. | Nothing | — |
forms_notification_limit |
Notification limit reached for today. Form notifications are limited per day. This one waits until the next UTC day. | No action needed. | Wait | — |
forms_permission_unknown |
Outcome unknown: form permission. The hand-over may have succeeded, but we could not confirm it. It may already have been delivered. | Do not resend. Wait for delivery evidence or contact support. | Wait | Do not resend |
lease_expired_in_dispatch |
Outcome unknown: sending was interrupted. Sending was interrupted after it may have reached the relay. It may already have been delivered. | Do not resend. Wait for delivery evidence or contact support. | Wait | Do not resend |
lease_lost |
Outcome unknown: attempt interrupted. The hand-over may have succeeded, but we could not confirm it. It may already have been delivered. | Do not resend. Wait for delivery evidence or contact support. | Wait | Do not resend |
missing_provider_id |
Outcome unknown: no receipt. The hand-over may have succeeded, but we could not confirm it. It may already have been delivered. | Do not resend. Wait for delivery evidence or contact support. | Wait | Do not resend |
not_recorded |
No cause recorded. This change happened before causes were recorded, or without one. | Contact support with the message ID if you need to know why. | Support | Do not resend |
outcome_unknown |
Outcome unknown. We did not get a clear answer about this message. It may already have been delivered. | Do not resend. Wait for delivery evidence or contact support. | Wait | Do not resend |
payload_integrity |
Stored message failed its integrity check. A safety check stopped this message before it was handed over. | Contact support with the message ID. Do not send it again under another sender. | Support | Do not resend |
permanent_rejection |
Permanently rejected. The receiving side rejected the message permanently. It will not be retried. | Check the recipient address and content. Contact support with the message ID if it is unclear. | Fix | — |
provider_ambiguous |
Outcome unknown: unclear answer. The hand-over may have succeeded, but we could not confirm it. It may already have been delivered. | Do not resend. Wait for delivery evidence or contact support. | Wait | Do not resend |
recipient_not_allowlisted |
Recipient not allowed in this mode. A safety check stopped this message before it was handed over. | Contact support with the message ID. Do not send it again under another sender. | Support | Do not resend |
recipient_suppressed |
Recipient is blocked. The address is suppressed, for example after a permanent bounce or a complaint. | Treat the address as invalid and ask the user to confirm or change it. | Fix | — |
response_lost |
Outcome unknown: no answer received. The hand-over may have succeeded, but we could not confirm it. It may already have been delivered. | Do not resend. Wait for delivery evidence or contact support. | Wait | Do not resend |
retry_after_expiry |
Expired while retrying. A temporary refusal was still being retried when the expiry time passed. It was not sent. | Send a new message if it is still needed. It is not a duplicate. | Nothing | — |
routing_changed |
Sending route changed. A safety check stopped this message before it was handed over. | Contact support with the message ID. Do not send it again under another sender. | Support | Do not resend |
send_cap_reached |
Service sending limit reached. A safety check stopped this message before it was handed over. | Contact support with the message ID. Do not send it again under another sender. | Support | Do not resend |
sender_not_trusted |
Sender not trusted for this route. A safety check stopped this message before it was handed over. | Contact support with the message ID. Do not send it again under another sender. | Support | Do not resend |
signing_failed |
Signing failed. A safety check stopped this message before it was handed over. | Contact support with the message ID. Do not send it again under another sender. | Support | Do not resend |
smtp_ambiguous |
Outcome unknown: unclear relay answer. The hand-over may have succeeded, but we could not confirm it. It may already have been delivered. | Do not resend. Wait for delivery evidence or contact support. | Wait | Do not resend |
smtp_gate_failed |
Relay check failed. A safety check stopped this message before it was handed over. | Contact support with the message ID. Do not send it again under another sender. | Support | Do not resend |
smtp_unreachable |
Relay unreachable. We could not reach our sending relay. Nothing was handed over. | No action needed. It is retried until it expires. | Wait | — |
suppressed |
Recipient is blocked. The address was suppressed just before sending. | Treat the address as invalid and ask the user to confirm or change it. | Fix | — |
temporary_refusal |
Temporarily refused. The receiving side refused the message for now. We retry automatically until it expires. | No action needed. It will be retried. | Wait | — |
timeout |
Outcome unknown: timed out. The hand-over may have succeeded, but we could not confirm it. It may already have been delivered. | Do not resend. Wait for delivery evidence or contact support. | Wait | Do not resend |
transport_skipped_final_gate |
Final check was not passed. A safety check stopped this message before it was handed over. | Contact support with the message ID. Do not send it again under another sender. | Support | Do not resend |
unreachable |
Sending service unreachable. We could not reach the sending service. Nothing was handed over. | No action needed. It is retried until it expires. | Wait | — |
unrenderable_message |
Message could not be prepared. A safety check stopped this message before it was handed over. | Contact support with the message ID. Do not send it again under another sender. | Support | Do not resend |
Replies from the receiving side
Section titled “Replies from the receiving side”SMTP and HTTP reply codes are grouped by class: smtp_4xx and http_4xx are temporary, smtp_5xx and http_5xx permanent. The exact code stays visible next to the class.
| Code | What it means | What to do | Next | Retry |
|---|---|---|---|---|
smtp_5xx, http_5xx |
Rejected by the relay. The relay rejected the message permanently. | Check the address and content, or contact support with the message ID and code. | Fix | — |
smtp_4xx, http_4xx |
Temporarily refused. The relay answered with a temporary refusal. We retry automatically until it expires. | No action needed. | Wait | — |
Delivery reports
Section titled “Delivery reports”Classes of the enhanced status code in a delivery report (RFC 3463), as in feedback.status.
| Code | What it means | What to do | Next | Retry |
|---|---|---|---|---|
dsn_bad_address |
Address does not exist. The recipient’s server says this mailbox or domain does not exist. The address is now blocked. | Correct the address with your user. | Fix | — |
dsn_mailbox_full_permanent |
Mailbox full. The recipient’s mailbox is full and the server gave up. | Ask your user to free space or use another address. | Fix | — |
dsn_mailbox_full_temporary |
Mailbox full for now. The recipient’s mailbox is full. The receiving side keeps retrying. | No action needed yet. | Wait | — |
dsn_permanent_other |
Permanently refused. The recipient’s server refused the message permanently. | Check the address and content, or contact support with the message ID and code. | Fix | — |
dsn_policy |
Refused by recipient policy. The recipient’s server refused the message for policy or authentication reasons. | Check domain authentication on the project home. If it is healthy, contact support with the code. | Fix | — |
dsn_success |
Accepted onward. A receiving server reported success or passed the message on. | No action needed. This does not prove inbox placement. | Nothing | — |
dsn_temporary |
Delayed by the recipient’s server. The recipient’s server deferred the message. The receiving side keeps retrying. | No action needed yet. | Wait | — |
Sending limits
Section titled “Sending limits”The error.reason of a 429 response. See API errors.
| Code | What it means | What to do | Next | Retry |
|---|---|---|---|---|
daily_limit_reached |
Daily limit reached. Your daily sending limit is used up. It resets at 00:00 UTC. | Retry after Retry-After with the same idempotency key. | Wait | Same key |
lifetime_limit_reached |
Total limit reached. Your total sending limit is used up. It does not reset. | Contact us to raise it. Waiting does not help. | Support | Same key |
monthly_limit_reached |
Monthly limit reached. Your monthly sending limit is used up. It resets on the first day of the next UTC month. | Retry after Retry-After with the same idempotency key, or contact us about your plan. | Wait | Same key |
pending_limit_reached |
Too many messages waiting. Too many of your messages are still waiting to be sent. | Retry later with the same idempotency key. Check the message list for held messages. | Wait | Same key |
rate_limited |
Sending too fast. You sent more messages in a short window than your plan allows. | Retry after Retry-After with the same idempotency key. | Wait | Same key |
service_capacity |
Service capacity reached. The service has reached a shared sending limit. This is not about your own usage. | Retry after Retry-After with the same idempotency key. If there is none, contact support. | Wait | Same key |
test_storage_limit_reached |
Test storage full. Captured test mail for this project has reached its storage allowance. | Retry after Retry-After with the same idempotency key; captures are purged after seven days. | Wait | Same key |
Project health
Section titled “Project health”Issues on the project home and the Service status page.
| Code | What it means | What to do | Next | Retry |
|---|---|---|---|---|
allowance_exhausted |
Sending limit reached. You have reached one of your sending limits. | See Sending allowance below for when it resets. Only our team can raise a lifetime limit. | Wait | — |
allowance_warning |
Approaching a sending limit. You have used at least 80% of one of your sending limits. | See Sending allowance below for when it resets. | Nothing | — |
authentication_failed |
Domain records need fixing. Your DKIM, SPF, bounce or DMARC records do not match what we expect. | Compare your DNS with the records on the project page. Keep your existing mail settings. | Fix | — |
authentication_stale |
Domain check is out of date. We have not been able to recheck how your domain authenticates mail recently. | Keep your published DNS records in place. Contact us if this does not clear. | Wait | — |
credential_expired |
A credential has expired. Messages sent with an expired credential may be on hold. | Check your credentials and contact us about any held messages. | Fix | — |
credential_expiring |
A credential expires soon. An API key or SMTP login expires within 7 days. | Create a replacement and switch over before it expires. | Fix | — |
credential_unavailable |
No active credentials. This project has no active API key or SMTP login. | Create one on the API keys & SMTP page after domain setup. | Fix | — |
dispatch_held |
Sending is paused. We paused sending while we recover from a service problem. | Our team needs to review queued messages before they can be released. They may expire while waiting. | Wait | — |
domain_revoked |
Domain removed. This domain registration was removed and no longer confirms that you own the domain. | Contact us before you change any DNS records. | Support | — |
grant_expired |
Sending access expired. Sending access has expired. | Contact us if access does not recover. Messages waiting to go out may expire in the meantime. | Support | — |
grant_expiring |
Sending access expires soon. Sending access expires within 7 days. | Contact us if it is not renewed. Messages explicitly placed on hold remain on hold. | Support | — |
grant_unavailable |
Sending setup pending. Sending setup is incomplete, or this project is limited to test messages. | Check your domain records and credentials. Contact us if sending remains unavailable. | Fix | — |
historical_valuation |
Past usage needs review. Some of your past sending could not be fully priced. | Contact us to resolve it. Past usage is not erased to free up capacity. | Support | — |
messages_held |
Messages on hold. Some of your messages are on hold. Check their history before sending them again. | See why on the Messages page, or contact us to release or cancel them. | Support | — |
organization_suspended |
Sending is stopped for your organization. Your organization is suspended. | Contact us to find out why and what happens next. | Support | — |
ownership_stale |
Domain ownership needs rechecking. We could not confirm your domain ownership recently. | Check that the ownership record is still published, then check again. Leave your existing mail records as they are. | Fix | — |
preparation_pending |
We are preparing your domain. Signing and routing for your domain are not set up yet. | Follow the domain setup steps. Contact us if preparation remains stuck. | Wait | — |
price_unavailable |
Your sending limits cannot be confirmed. Your current plan or pricing details are unavailable. | Contact us. Sending stays restricted until this is resolved, even if you have not sent anything yet. | Support | — |
recipient_suppressed |
Some recipients are blocked. We stopped sending to some addresses, for example after a bounce or complaint. | See which ones on the Messages page. Contact us before you try them again. | Fix | — |
setup_required |
Setup not finished. This project is not ready to send yet. | Finish connecting your sending domain, or contact us if you are stuck. | Fix | — |
stream_paused |
Sending is paused for safety. Our team paused sending from this project. | Contact us to review it. Customers cannot override this pause. | Support | — |
stream_review |
Sending is under review. Our team is reviewing sending from this project. | Contact us for details. Resetting your usage does not end the review. | Support | — |
submission_unknown |
Message outcome unknown. We sent a message but did not get a clear answer back. It may already have been delivered. | Do not resend it, or the recipient may get it twice. Wait for an update or contact us. | Wait | Do not resend |
webhook_failed |
Webhook is not receiving events. We could not deliver events to one of your webhook endpoints. | Check your endpoint and the webhook history. A webhook failure never resends email. | Fix | — |
Unrecognised code
Section titled “Unrecognised code”A code this page does not list is shown as it is, never hidden. Contact support with the message ID and the code, and do not resend.