---
title: "Email Webhook Failure Codes"
slug: "email-webhook-failure-codes"
updated: 2026-07-08T16:12:53Z
published: 2026-07-08T16:12:53Z
canonical: "docs.xtremepush.com/email-webhook-failure-codes"
stale: true
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xtremepush.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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` |