Postfix DSN reference: RFC 3463 enhanced status codes
Enhanced Status Codes (DSN codes) appear in Postfix logs to categorize the outcome of mail delivery attempts. Understanding them helps you quickly identify whether a delivery failure is temporary (transient), permanent, or a success.
How to read a DSN code
Section titled “How to read a DSN code”A DSN code follows the format class.subject.detail (X.Y.Z), where each digit carries specific meaning.
class.subject.detail. Read the first digit first: it tells you whether Postfix will retry (4) or has given up (5).Class (first digit):
2= Success. The delivery attempt succeeded.4= Persistent Transient Failure. The server will retry. Try again later.5= Permanent Failure. The message cannot be delivered. Do not retry.
Subject (second digit): According to RFC 3463, the subject groups the failure reason:
0= Other or undefined1= Addressing status (bad recipient address, invalid syntax, etc.)2= Mailbox status (mailbox unavailable, over quota, disabled, etc.)3= Mail system status (mail system congestion, insufficient storage, etc.)4= Network and routing status (no route to host, bad connection, timeout, etc.)5= Mail delivery protocol status (SMTP protocol error, authentication failure, etc.)6= Message content or media status (invalid header, unsupported media type, etc.)7= Security or policy status (delivery not authorized, blocked by policy, etc.)
Detail (third digit):
Provides further specificity within the subject. For example, 4.4.1 indicates a persistent transient network issue specifically describing a host that did not answer.
Where DSN codes appear in Postfix logs
Section titled “Where DSN codes appear in Postfix logs”DSN codes appear in the dsn= field of Postfix smtp and lmtp lines. Example line from mail.log:
Jun 17 10:15:22 mail postfix/smtp[1234]: ABC123DEF456: to=<user@example.com>, relay=mail.example.com[192.0.2.1], delay=0.45, delays=0.12/0.01/0.22/0.10, dsn=2.0.0, status=sent (250 OK)The dsn=2.0.0 indicates success. The status= field (sent, deferred, or bounced) is separate and describes Postfix’s handling; the dsn= is the remote server’s enhanced status code.
Distinction from other codes:
- DSN (Delivery Status Notification) codes: RFC 3463. The
dsn=X.Y.Zfield. - SMTP reply codes: RFC 5321. The 3-digit numeric reply (e.g.,
250,450,550). Usually shown in parentheses after the reason text. - Bounce message format: RFC 3464. The structure of NDR (non-delivery report) emails.
Common DSN codes and diagnosis
Section titled “Common DSN codes and diagnosis”| Code | Type | Meaning | What to Check |
|---|---|---|---|
2.0.0 | Success | Message delivered successfully. | No action needed. |
4.2.2 | Transient | Mailbox full (temporary). | Check recipient’s mailbox size limit and ask them to delete old mail. Try delivery again later. |
4.3.0 | Transient | System unavailable (mail server temporarily down, overloaded, or out of storage). | Check if the remote mail server is online. Review its error logs. Wait and retry. |
4.4.1 | Transient | No answer from host (connection timeout). | Verify the MX record for the domain. Check network connectivity to the mail server. The server may be slow or temporarily offline. |
4.4.2 | Transient | Bad connection (socket error, protocol error, or server hung up unexpectedly). | Check network stability to the remote server. It may have dropped the connection due to a resource issue. |
4.7.0 | Transient | Temporary policy failure (e.g., greylisting or rate limiting). | The remote server is applying a temporary block, often as anti-spam measure. Retry later; the server will accept on subsequent attempts. |
4.7.1 | Transient | Temporary authentication failure (e.g., SPF/DKIM check failed temporarily, or credentials rejected). | Verify sender SPF/DKIM records. Confirm authentication credentials if relay auth is used. Check if the remote server’s policy check is misconfigured. |
5.1.1 | Permanent | Bad destination mailbox (user does not exist or address is invalid). | Verify the recipient email address is correct. Check with the recipient’s organization that the account exists and address is current. |
5.1.2 | Permanent | Bad destination system (domain does not exist or has no MX record). | Confirm the domain name is spelled correctly. Check that an MX record exists for the domain: dig example.com MX. If missing, contact the domain administrator. |
5.2.1 | Permanent | Mailbox disabled (user account has been deactivated). | Contact the recipient’s organization. The mailbox has been permanently disabled or deleted. |
5.2.2 | Permanent | Mailbox full (over quota, permanent). | Unlike 4.2.2, the server will not accept further mail. Recipient must delete mail or increase quota. |
5.4.4 | Permanent | Unable to route (no MX record, routing impossible, or domain misconfigured). | Check MX records for the destination domain. Confirm the domain is properly configured in DNS. A NXDOMAIN or missing MX indicates a permanent issue. |
5.7.1 | Permanent | Delivery not authorized / blocked by policy (sender not allowed, not authenticated, or explicitly blocked). | Check sender authentication (DKIM, SPF, DMARC). Verify the sender is not on a block list. Review the remote server’s policy (e.g., requires DKIM, rejects certain countries). |
5.7.26 | Permanent | Multiple authentication checks failed (DMARC, SPF, DKIM, or other authentication validation). | Verify sender domain’s DMARC policy is properly configured. Check SPF and DKIM record alignment and syntax. The remote server is rejecting due to authentication failures. |
Transient vs. permanent: the same code, different class
Section titled “Transient vs. permanent: the same code, different class”The same issue can be coded as transient (4.x.x) or permanent (5.x.x) depending on how the remote server interprets it. For example:
4.2.2: mailbox is temporarily full; the server expects it to have space later.5.2.2: mailbox is permanently full; the recipient’s quota cannot be increased.
Similarly:
4.7.1: authentication check failed temporarily (may retry successfully).5.7.1: delivery is permanently denied by policy.
Always read the status= field and the time context together with the DSN code. Transient failures (4.x.x) will show status=deferred; Postfix will retry. Permanent failures (5.x.x) show status=bounced and generate an NDR to the sender.
For the authentication codes (4.7.1, 5.7.1, 5.7.26), confirm the sending domain’s SPF, DKIM, and DMARC with the Email Authentication Checker, and inspect a specific failing message with the Email Header Analyzer.
Using Postfix Insights to analyze DSN codes
Section titled “Using Postfix Insights to analyze DSN codes”Postfix Insights aggregates delivery outcomes by DSN code, showing you which codes dominate your mail flow. Use the dashboard to:
- Identify which failure codes occur most frequently in your environment.
- Spot patterns (e.g., many
5.1.1codes point to a list hygiene problem; many4.4.1codes suggest a network or routing issue with a specific domain). - Drill into individual messages for detail and context.
For deeper guidance on troubleshooting bounced and deferred mail:
Next steps
Section titled “Next steps”- Get started with Quick start.
- Explore the Postfix Insights repository.