Email Bounce Codes Reference (DSN)

Command references used in this guide: nylas email search, nylas email read, and nylas email list.

What is a DSN and where is the bounce code?

A DSN is a delivery status notification: an automated email a receiving mail server returns when it cannot deliver your message. Defined in RFC 3464, it arrives from a mailer-daemon or postmaster address and carries a machine-readable enhanced status code separate from the human-readable bounce text.

The enhanced status code follows RFC 3463 and takes the form class.subject.detail — three dot-separated numbers such as 5.1.1. It sits in a message/delivery-status MIME part under a Status: field, alongside the original SMTP reply. There are over 70 registered codes in the IANA enhanced status code registry, but a handful cover most real bounces. The text part is provider-specific and inconsistent; the numeric code is standardized, which is why parsing it beats grepping the prose.

# A DSN's machine-readable part looks like this (RFC 3464 message/delivery-status):
# Reporting-MTA: dns; smtp.example.com
# Final-Recipient: rfc822; nobody@example.com
# Action: failed
# Status: 5.1.1            <- the RFC 3463 enhanced status code
# Diagnostic-Code: smtp; 550 5.1.1 No such user here

What is the difference between a hard and soft bounce?

The first digit of the enhanced status code decides it. A 5.x.x code is a hard bounce: a permanent failure where the server says delivery will never succeed, so you should stop sending to that address. A 4.x.x code is a soft bounce: a transient failure where the server expects the problem to clear, so the sender retries automatically.

Retry behavior follows RFC 5321: a sending MTA holds a soft-bounced message in its queue and retries on a backoff schedule, typically giving up and returning a final DSN after 4 to 5 days. A hard bounce produces no retry — the failure is reported immediately. Treating the two the same is the most common mailing-list mistake: retrying a 5.x.x wastes sender reputation, while suppressing an address after a single 4.x.x drops a recipient who was only briefly unreachable. The rule is simple: suppress on 5.x.x, retry on 4.x.x.

Class digit   Bounce type   Meaning                         Sender action
2.x.x         success       delivered / accepted            none
4.x.x         soft          transient failure, will retry   wait, retry later
5.x.x         hard          permanent failure               suppress the address

Which enhanced status codes appear most often?

Five RFC 3463 codes account for the majority of bounces a sender sees. 5.1.1 (no such user) and 5.1.2 (bad domain) are permanent address failures. 5.2.2 (mailbox full) and 4.2.2 are quota problems that differ only by class. 5.7.1 is a policy or spam rejection. Knowing these five decodes most DSNs without a lookup.

The subject digit (the middle number) groups the cause: x.1.x is an addressing problem, x.2.x is a mailbox problem, x.7.x is a security or policy problem. So 5.7.1 and 5.7.26 are both policy rejections — the latter is a modern DMARC/authentication failure that Gmail began enforcing in February 2024. The detail digit narrows it further. The table maps the codes you will see on more than 90% of bounces, drawn from the IANA registry.

How do I find bounce messages with the CLI?

The nylas email search command queries your mailbox by sender, so a search for the mailer-daemon address surfaces every DSN that landed in your inbox. Bounces almost always come from a mailer-daemon@ or postmaster@ sender, which makes the --from filter the fastest way to collect them. The --json flag returns structured output for scripting.

Pass "*" as the query to match any subject, then filter by sender. The default result limit is 20; raise it with --limit, which auto-paginates past 200. Combine it with --after to scope a recent send. One command replaces logging into a webmail UI and manually scanning for failure notices.

# Find every bounce notification from the mail daemon in your inbox
nylas email search "*" --from "mailer-daemon@googlemail.com" --json --limit 50

# Scope to bounces that arrived after a specific send date
nylas email search "*" --from "postmaster@outlook.com" --after 2026-06-01 --json

How do I read the enhanced status code out of a bounce?

The nylas email read command displays a single message by ID, and its --raw flag shows the unprocessed body so the message/delivery-status MIME part with the Status: field is visible. The --headers flag adds the full header block, which carries the original recipient and the diagnostic SMTP reply for the failed delivery.

First grab a message ID from the search above, then read it raw to expose the enhanced status code. Piping search JSON through jq extracts IDs in one line, so you can loop over a batch of bounces and pull the 3-digit class.subject.detail code from each. The numeric code is stable across providers, unlike the human-readable text, so a parser keyed on the Status: line works for Gmail and Microsoft alike without rewriting it for every provider in 2026.

# Get the message ID of the most recent bounce
ID=$(nylas email search "*" --from "mailer-daemon@googlemail.com" --json --limit 1 | jq -r '.[0].id')

# Read it raw to expose the RFC 3463 Status: line and SMTP diagnostic code
nylas email read "$ID" --raw --headers | grep -iE "^Status:|Diagnostic-Code:|Final-Recipient:"

Next steps

• Soft Bounce vs Hard Bounce Explained — Soft bounces (4xx) are transient and retried for up to 5 days;…
• Fix Garbled Email Encoding (Mojibake) — Diagnose mojibake from raw MIME headers
• AI Agent Email Bounce Detection and Retry — Deterministic bounce rules for AI agents
• Handle email bounces with the CLI — automate suppression on hard bounces
• SMTP reply codes explained — the 3-digit codes behind enhanced status codes
• Debug email delivery — when a sent message never arrives
• Export contacts to CSV — build a suppression list from bounced addresses
• Dedupe contacts — clean an address book before a send
• Full command reference — every flag and subcommand documented
• RFC references: RFC 3463 (enhanced status codes), RFC 3464 (DSN format), and RFC 5321 (SMTP retry timing)