Delivery Status Notification (DSN)
A Delivery Status Notification (DSN) is the message returned by a mail server after accepting or rejecting incoming E-Mail. Rejected messages are also referred to as bounces.
A typical failure notification or bounce could look like this:
554 5.7.1 <user@domain.tld>: Recipient address rejected: Access denied
A typical success notification could look like this:
250 2.0.0 Requested mail action okay, completed: id=1a2B3c4D-6F7g8H9i1J-00A1BC
We see 3 things:
- Basic status codes, for example 554 and 250.
- Enhanced status codes, for example 5.7.1 and 2.0.0.
- Plus a bunch of text, with a humanly readable description of events.
Status types and definitions
The below text is partly quoted from Wikipedia:
Basic status codes
A "Basic Status Code" SMTP reply consists of a three digit number (transmitted as three numeric characters) followed by some text. The number is for use by automata (e.g., email clients) to determine what state to enter next; the text ("Text Part") is for the human user.
The first digit denotes whether the response is good, bad, or incomplete:
| Status Code Group | Group Name | Description |
|---|---|---|
| 1xx | Informational | Request received, continuing process |
| 2xx | Success | The action was successfully received, understood, and accepted |
| 3xx | Redirection | Further action must be taken in order to complete the request |
| 4xx | Client Error | The request contains bad syntax or cannot be fulfilled |
| 5xx | Server Error | The server failed to fulfil an apparently valid request |
The second digit encodes responses in specific categories:
- x0z (Syntax): These replies refer to syntax errors, syntactically correct commands that do not fit any functional category, and unimplemented or superfluous commands.
- x1z (Information): These are replies to requests for information.
- x2z (Connections): These are replies referring to the transmission channel.
- x3z : Unspecified.
- x4z : Unspecified.
- x5z (Mail system): These replies indicate the status of the receiver mail system.
Enhanced status codes
The Basic Status Codes have been in SMTP from the beginning, with RFC821 in 1982, but were extended rather extensively, and haphazardly so that by 2003 RFC3463 rather grumpily noted that: "SMTP suffers some scars from history, most notably the unfortunate damage to the reply code extension mechanism by uncontrolled use."
RFC3463 defines a separate series of enhanced mail system status codes which is intended to be better structured, consisting of three numerical fields separated by ".", as follows:
class "." subject "." detail class = "2" / "4" / "5" subject = 1 to 3 digits detail = 1 to 3 digits
The below text is quoted from the IANA SMTP Enhanced Status Codes Registry:
The classes are defined as follows:
| Code | Summary | Description | Reference |
|---|---|---|---|
| 2.XXX.YYY | Success | Success specifies that the DSN is reporting a positive delivery action. Detail sub-codes may provide notification of transformations required for delivery. | RFC3463 (Standards track) |
| 4.XXX.YYY | Persistent Transient Failure | A persistent transient failure is one in which the message as sent is valid, but persistence of some temporary condition has caused abandonment or delay of attempts to send the message. If this code accompanies a delivery failure report, sending in the future may be successful. In this case, the bounce will be classified as a soft-bounce. | RFC3463 (Standards track) |
| 5.XXX.YYY | Permanent Failure | A permanent failure is one which is not likely to be resolved by resending the message in the current form. Some change to the message or the destination must be made for successful delivery. | RFC3463 (Standards track) |
For an extensive list on Class Sub-Codes, visit IANA or look at RFC3463.
Types of bounces
Bounces are DSN's with a status code either starting with 4 (transient/temporary) or 5 (permanent). If a bounce is received, one of the following actions can be taken:
- to stop sending to the bouncing address immediately.
- to try a few more times and stop sending if it continuously doesn't work.
- to keep on sending to the address in question, despite the bounce.
It's unfortunate to have only two types status codes, when there are three types of actions possible. This way, we can't pick the desired action merely based on the status code.
Hardbounces (5XX)
Hardbounces are always permanent bounces, but not all permanent bounces are hardbounces. The classic example of a hardbounce, is a non-existing mailbox. Hardbounces should never be retried. Once a hardbounce is received, the address in question is never to be sent to again. Non existing mailboxes can be transformed to recycled spamtraps. Therefore it's important regularly send to your active list and never send to previously hardbounced contacts.
Softbounces (4XX)
Softbounces are always temporary bounces, but not all temporary bounces are softbounces. Classic examples of softbounces are a full mailbox, or a network timeout. Softbounces should be retried, but not forever. A rule of fist is to stop sending after a maximum of 4 softbounces from the same recipient.
But what about "Blockbounces"?
The third scenario, is where a message is blocked due to policy reasons. In this case, the reason for the block should be mitigated and sending should continue. Sender reputation isn't negotiated when no sending is taking place. Therefore it's important never to stop sending to blockbounced addresses. Blockbounces can be either permanent (5XX) or transient (4XX).
Bounce processing
The big question that remains is how to process three bounce types when only two status types are bounces? The only way to do this, is by using regular expressions on the humanly readable text in the DSN. For example, any message where the DSN text contains words such as "spam", "policy" or "blocked" can be safely regarded blockbounces. Commonly, classification of bounces is done in the following order:
- Try to find a classification based on regex.
- If no classsification can be determined, it's either a hardbounce (5XX) or a softbounce (4XX).
Mapping tables
In case regex isn't possible and it's required to map status codes to messages, the following tables can be used:
Most frequent enhanced 5.X bounce codes (permanent failures)
| Code | Description |
|---|---|
| 5.0.0 | Address does not exist |
| 5.1.0 | Other address status |
| 5.1.1 | Bad destination mailbox address |
| 5.1.2 | Bad destination system address |
| 5.1.3 | Bad destination mailbox address syntax |
| 5.1.4 | Destination mailbox address ambiguous |
| 5.1.5 | Destination mailbox address invalid |
| 5.1.6 | Mailbox has moved |
| 5.1.7 | Bad sender’s mailbox address syntax |
| 5.1.8 | Bad sender’s system address |
| 5.2.0 | Other or undefined mailbox status |
| 5.2.1 | Mailbox disabled, not accepting messages |
| 5.2.2 | Mailbox full |
| 5.2.3 | Message length exceeds administrative limit. |
| 5.2.4 | Mailing list expansion problem |
| 5.3.0 | Other or undefined mail system status |
| 5.3.1 | Mail system full |
| 5.3.2 | System not accepting network messages |
| 5.3.3 | System not capable of selected features |
| 5.3.4 | Message too big for system |
| 5.4.0 | Other or undefined network or routing status |
| 5.4.1 | No answer from host |
| 5.4.2 | Bad connection |
| 5.4.3 | Routing server failure |
| 5.4.4 | Unable to route |
| 5.4.5 | Network congestion |
| 5.4.6 | Routing loop detected |
| 5.4.7 | Delivery time expired |
| 5.5.0 | Other or undefined protocol status |
| 5.5.1 | Invalid command |
| 5.5.2 | Syntax error |
| 5.5.3 | Too many recipients |
| 5.5.4 | Invalid command arguments |
| 5.5.5 | Wrong protocol version |
| 5.6.0 | Other or undefined media error |
| 5.6.1 | Media not supported |
| 5.6.2 | Conversion required and prohibited |
| 5.6.3 | Conversion required but not supported |
| 5.6.4 | Conversion with loss performed |
| 5.6.5 | Conversion failed |
| 5.7.0 | Other or undefined security status |
| 5.7.1 | Delivery not authorized, message refused |
| 5.7.2 | Mailing list expansion prohibited |
| 5.7.3 | Security conversion required but not possible |
| 5.7.4 | Security features not supported |
| 5.7.5 | Cryptographic failure |
| 5.7.6 | Cryptographic algorithm not supported |
| 5.7.7 | Message integrity failure |
Most frequent basic status codes
| Code | Description |
|---|---|
| 421 | domain service not available, closing transmission channel |
| 450 | Requested mail action not taken: mailbox unavailable (e.g., mailbox busy) |
| 451 | Requested action aborted: error in processing |
| 452 | Requested action not taken: insufficient system storage |
| 500 | The server could not recognize the command due to a syntax error |
| 501 | A syntax error was encountered in command arguments |
| 502 | This command is not implemented |
| 503 | The server has encountered a bad sequence of commands |
| 504 | A command parameter is not implemented |
| 550 | User’s mailbox was unavailable (“not found”) |
| 551 | The recipient is not local to the server |
| 552 | The action was aborted due to exceeded storage allocation |
| 553 | The command was aborted because the mailbox name is invalid |
| 554 | The transaction failed for some unstated reason |