Email Webhook Failure Codes

When an email message fails to deliver, two additional fields are included in the webhook payload:

failure_status_code: A numeric code identifying why a message failed to deliver.
is_permanent: Whether the failure is permanent or temporary.
- A value of true indicates a permanent failure. Only codes 1, 15, and 100 in the table below are permanent failures. We recommend suppressing the address in your system and not retrying.
- A value of false indicates a temporary failure that may succeed on retry.

These fields appear on message_bounce, message_complaint, and message_failure events only. For non-email channels, these fields are not applicable and return null.

The table below lists all possible failure_status_code values.

`failure_status_code`	Name	Description	`is_permanent`
0	UNKNOWN	The reason for the failure could not be determined.	`false`
1	HARD_BOUNCE_BAD_MAILBOX	The recipient mailbox does not exist or the address is invalid.	`true`
2	SOFT_BOUNCE_QUOTA	The recipient's mailbox is full and cannot accept any further incoming messages.	`false`
3	SOFT_BOUNCE_MAILBOX_INACTIVE	The mailbox exists but is inactive.	`false`
4	SPAM_RELATED	The email was classified as spam by the recipient's mail server. Review your email content and sender reputation.	`false`
5	CONTENT_REJECT	The email was rejected due to its content, for example, size, attachments, or format. Review your email content, as retrying is unlikely to succeed.	`false`
6	POLICY_RELATED	The email was rejected due to a policy at the recipient's mail server, for example, a rate limit, IP block, or regional policy. Retry may succeed.	`false`
7	BAD_DOMAIN	The email domain has DNS or MX record issues. This may resolve later.	`false`
8	INVALID_SENDER	The sender address was rejected due to a configuration or authentication issue.	`false`
9	INTERNAL_ERROR	The recipient's mail server reported an internal error. Retry later.	`false`
10	MESSAGE_EXPIRED	The message could not be delivered after multiple attempts. Retry may succeed.	`false`
11	NO_ANSWER_FROM_HOST	The recipient's mail server could not be reached. Retry later.	`false`
12	NETWORK_ERRORS	A network-level failure occurred between the sender and the recipient's email provider. Retry later.	`false`
13	TEMPORARILY_DEFERRED	The recipient's email provider deferred delivery. Retry later.	`false`
14	AUTO_REPLY	An automated reply was received, such as an out-of-office or vacation message. This is not a delivery failure and does not affect the recipient's addressability.	`false`
15	SUPPRESSED	The recipient is on the email provider's suppression list. This is a permanent failure. Do not retry sending.	`true`
100	COMPLAINT	The recipient marked the message as spam. This is a permanent failure. Do not retry sending.	`true`

Documentation Index

Email Webhook Failure Codes