Bounce message decoder

A bounce is a report written by a server

When you send an email, your provider’s server hands it to the recipient’s server. If the handover fails, the recipient’s server answers with a refusal line, and your own server wraps that line in a message addressed to you. The sender shows up as “Mail Delivery Subsystem”, “MAILER-DAEMON” or “postmaster”, because no person wrote it.

The notice comes in two layers. On top there’s a sentence meant for humans, often a vague one (“Address not found”, “Message not delivered”). The useful part is underneath, in a small machine-readable report:

Final-Recipient: rfc822; anna@example.org
Action: failed
Status: 5.1.1
Remote-MTA: dns; mx.example.org
Diagnostic-Code: smtp; 550 5.1.1 User unknown

Final-Recipient is the address that failed. Action says whether the server gave up (failed) or is still trying (delayed). Remote-MTA is the server that said no, and Diagnostic-Code quotes its exact words.

Two codes, read from left to right

The refusal line usually carries two numbers. The first has three digits, such as 550, and is the basic SMTP reply. The second is three numbers joined by dots, such as 5.1.1. That’s the enhanced status code, and it’s the more precise of the two.

In both, the first digit tells you what happens next. A 4 is a temporary refusal, so your server keeps the message in a queue and tries again by itself. A 5 is permanent and nothing more will be attempted. The middle number of the enhanced code gives the subject:

Large providers add their own numbers to the list. Microsoft 365 uses codes like 5.7.708 and 5.4.316. Gmail adds a keyword at the end of the line, such as gsmtp, and a support link.

How the decoder reaches its answer

Everything runs in your browser. The decoder starts by pulling out the facts: every enhanced code, every basic reply code it knows (from 421 to 556), the failed recipients, the server that refused, any IP address in square brackets and the Action field.

Then it compares the text with a catalog of about fifty known situations. Each one is recognized by its characteristic wording (“blocked using”, “quota exceeded”, “greylisted”) and by its exact codes. Distinctive wording counts most, an exact code adds to it, and the best-scoring situation becomes the main explanation. Other strong candidates go under “Other possible explanations”, because one code can cover several causes. 5.7.1 alone can mean a blocklist, a content filter or a private rule.

Temporary or permanent comes from the Action field when there is one, otherwise from the first digit of the codes found. Each explanation names who has to act: you, your email provider or IT person, the recipient, or nobody yet because the server is still retrying.

The frequent causes and what to do

Unknown address or domain (5.1.1, 5.1.2)

Check the spelling, especially after the @. If it’s correct, the mailbox was closed, and you’ll have to ask for the new address some other way.

Mailbox over quota (5.2.2, 4.2.2)

Only the recipient can free up space. Let them know by phone or message.

Message too large (5.3.4)

Most providers stop around 20 to 25 MB, and attachments grow by a third in transit. Send a link to the file instead.

Authentication failures (5.7.26, 5.7.23, 5.7.30)

The receiving side couldn’t verify that your domain authorized the sending server. Run the SPF, DKIM and DMARC checkup on your domain and repair what it reports.

“Blocked using” a list name

Your sending server’s IP address is on a spam blocklist. The blocklist lookup shows which one. On shared hosting, forward the result to your provider.

Greylisting and other 4.x.x replies

Wait. Sending it again by hand creates duplicates and resets nothing. Servers usually retry for one to five days before they give up.