When an email bounces, tinyRelay sends a BOUNCED webhook event with a numeric bounceCategory. The 19 categories come down to four answers: stop sending, retry later, investigate, or keep sending.
"eventType": "BOUNCED", "subType": "HARD_BOUNCED", "bounceCategory": "10"
Stop sending to this address and add it to your own suppression list. Ask the user for a corrected address.
Full entry for 10 →"eventType": "BOUNCED", "subType": "SOFT_BOUNCED", "bounceCategory": "22"
The recipient's mailbox or quota is full. Retry later.
Full entry for 22 →"eventType": "BOUNCED", "subType": "SOFT_BOUNCED", "bounceCategory": "29"
Retry later. Many 29s at one domain point at the domain.
Full entry for 29 →"eventType": "BOUNCED", "subType": "SOFT_BOUNCED", "bounceCategory": "51"
Not specific to this message: it concerns the sending server itself. Send the bounceDescription to support.
Full entry for 51 →"eventType": "BOUNCED", "subType": "SOFT_BOUNCED", "bounceCategory": "55"
Check your SPF, DKIM and DMARC records, then resolve the complaint named in bounceDescription.
Full entry for 55 →"eventType": "BOUNCED", // subType: not documented for this category "bounceCategory": "60"
Generated by an auto-responder, such as a vacation reply. Do not suppress. Keep sending.
Full entry for 60 →Six of the 19 categories · source: the tinyRelay bounce categories docs
Pick an answer to see which of the 19 categories lead to it. The bar shows how the categories split.
Select a code to jump to its full entry. Source: the tinyRelay bounce categories docs.
Search all 19 codes →The event's subType says whether to keep sending: HARD_BOUNCED or SOFT_BOUNCED. The bounceCategory says why. Use subType when that is all you need, and the category when you need the reason.
Delivery to this address should not be attempted again. The docs ask you to add it to your own suppression list.
The address may well be valid. A retry is reasonable, though repeated soft bounces to one address or domain are worth acting on.
{
"eventType": "BOUNCED",
"subType": "SOFT_BOUNCED",
"receiver": "ann@example.com",
"metadata": { "order_id": "SO-1001" },
// the numeric category from this page
"bounceCategory": "22",
// the receiving server's raw diagnostic text (dsn_diag)
"bounceDescription": "…",
// the receiving server's DSN status code (dsn_status)
"bounceStatus": "…"
}Trimmed payload; values illustrative. Every field is in the webhook reference.
Delivery to this address should no longer be attempted. Usually it means the mailbox does not exist.
The recipient asked to be removed from the mailing list. Not a delivery failure, but treat it as final.
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.
A DNS lookup failed, either on the sending side or at a later relay server.
The recipient's mailbox or quota is full.
The destination server rejected the message because of its size.
The destination domain has no MX record.
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.
Positively identified as a bounce, but no more specific category could be determined.
A temporary delay in message transmission.
Rejected for a reason no more specific mail-block category covers.
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.
The remote server classified this message's content as spam.
Rejected because of one or more attachments.
The remote server refused to act as a relay for the message.
Refused on authentication policy. Resolving the specific complaint in bounceDescription usually improves deliverability.
We could not connect to the remote server, much like code 29.
The bounce processor received a message it could not classify as a bounce or as any other non-bounce code.
Generated by an auto-responder, such as a vacation reply.
No bounce code matches that search. Try a number such as 22, or a word such as block.
Verify the webhook signature first, then branch on the category: suppress on 10 and 90, never on 0 or 60, send mail blocks to a person, and retry the rest.
const STOP = new Set(["10", "90"]);
const NOT_BOUNCES = new Set(["0", "60"]);
const BLOCKS = new Set(["50", "51", "52", "53", "54", "55", "59"]);
function handleBounce(event) {
const cat = event.bounceCategory;
if (NOT_BOUNCES.has(cat)) return; // not a delivery failure
if (STOP.has(cat)) return suppress(event.receiver); // hard bounce
if (BLOCKS.has(cat)) return review(event); // read bounceDescription
return retryLater(event); // temporary failure
}A hard bounce means you should stop sending to the address. A soft bounce is a temporary failure or a block, and the address may well be valid. tinyRelay puts HARD_BOUNCED or SOFT_BOUNCED in the event's subType.
19. Two are hard bounces (10 and 90), eight are temporary failures (20, 21, 22, 23, 24, 29, 40 and 70), seven are mail blocks (50 to 55 and 59), and two are not bounces at all (0 and 60).
No. Category 0 is a message that could not be classified as a bounce, and 60 is an auto-reply such as a vacation message. Neither is a delivery failure, so keep sending.
In bounceDescription, which carries the raw diagnostic text the receiving server returned, and bounceStatus, which carries its DSN status code. Both arrive on the BOUNCED event next to bounceCategory.
Category 55 means the receiving server refused the message on SPF, DKIM or DMARC policy. Check your domain's records, then resolve the specific complaint named in bounceDescription. Fixing it usually improves deliverability.
SMTP relay or REST API, standalone or alongside tinyEmail. Tell us what you send and our team sets you up.