Bounce Categories
Webhook These are the bounce categories which are sent in the webhook response when an email gets bounced.
Where the category appears
When a message bounces we send a BOUNCED event to your webhook endpoint. Three fields on that payload describe the bounce:
| Field | Meaning |
|---|---|
bounceCategory | The numeric category from the tables below. |
bounceDescription | The raw diagnostic text the receiving server returned (dsn_diag). |
bounceStatus | The DSN status code the receiving server returned (dsn_status). |
The event's subType carries HARD_BOUNCED or SOFT_BOUNCED, which matches the grouping below. Use bounceCategory when you need the specific reason, and subType when all you need is whether to keep sending.
Hard bounces — stop sending to this address
Delivery to this address should not be attempted again. Add it to your own suppression list.
| Code | Category | Meaning |
|---|---|---|
| 10 | Bad email address | Delivery attempts to this address should no longer be attempted. Usually means the mailbox does not exist. |
| 90 | Unsubscribe | The recipient requested removal from the mailing list. Not a delivery failure, but treat it as final. |
Soft bounces — temporary, safe to retry
The address may well be valid. Retry is reasonable, though repeated soft bounces to the same address or domain are worth acting on.
Temporary failures
| Code | Category | Meaning |
|---|---|---|
| 20 | General | A possibly temporary delivery failure. The address may or may not be valid — often an ambiguous response such as a mailbox being "inactive" or "unavailable". |
| 21 | DNS failure | A DNS lookup failed, either at TinyEmail or at a subsequent relay server. |
| 22 | Mailbox full | The recipient's mailbox or quota is full. |
| 23 | Message too large | The destination server rejected the message because of its size. |
| 24 | Missing MX record | The destination domain has no MX record. |
| 29 | Unable to connect | We could not connect to the remote server. Many of these for one domain usually means the domain is not working, or is blocking your mail server. |
| 40 | General bounce | Positively identified as a bounce, but no more specific category could be determined. |
| 70 | Transient bounce | A temporary delay in message transmission. |
Mail blocks
The receiving server refused the message. These are worth investigating rather than simply retrying — several point at a sender reputation or authentication problem.
| Code | Category | Meaning |
|---|---|---|
| 50 | General | Rejected for a reason no more specific "mail block" category covers. |
| 51 | Known spammer | The remote server considers the sender a spammer. Not specific to this message — it concerns the sending server itself, often because of a public or private block list. |
| 52 | Spam detected | The remote server classified this message's content as spam. |
| 53 | Attachment detected | Rejected because of one or more attachments. |
| 54 | Relay denied | The remote server refused to act as a relay for the message. |
| 55 | SPF/DKIM/DMARC | Refused on authentication policy. Resolving the specific complaint in bounceDescription usually improves deliverability. |
| 59 | Unable to connect | We could not connect to the remote server, much like code 29. |
Not bounces
These codes appear in the same field but do not indicate a delivery failure. Do not suppress on them.
| Code | Category | Meaning |
|---|---|---|
| 0 | Non-bounce | The bounce processor received a message it could not classify as a bounce or as any other non-bounce code. |
| 60 | Auto-reply | Generated by an auto-responder, such as a vacation reply. |