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

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.

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

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 —

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 —

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

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 —

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.