SMTP Status Codes

From ASSPSMTP

Simple Mail Transfer Protocol (SMTP) status codes (sometimes referred to as SMTP error codes, SMTP reply codes, SMTP response codes, or SMTP return codes) are numerical values that represent the status of an e-mail transmission. They can be displayed as responses to commands issued during an SMTP session, or they can be an informative part of Delivery Status Notification (DSN) messages. DSN messages are commonly referred to as "bounce" messages.

On This Page 1 Identifying Status Codes 1.1 Example DSN 2 SMTP Status Codes 2.1 Positive Preliminary reply - 1xx 2.2 Positive Completion reply - 2xx 2.3 Positive Intermediate reply - 3xx 2.4 Transient Negative Completion reply - 4xx 2.5 Permanent Negative Completion reply - 5xx 3 Extended SMTP Status Codes 3.1 Class Sub-Codes - #.x.x 3.2 Subject Sub-Codes - x.#.x 3.3 Detail Sub-Codes - x.x.# 3.3.1 Other or Undefined Status 3.3.2 Address Status - x.1.# 3.3.3 Mailbox Status - x.2.# 3.3.4 Mail system status - x.3.# 3.3.5 Network and Routing Status - x.4.# 3.3.6 Mail Delivery Protocol Status - x.5.# 3.3.7 Message Content or Message Media Status - x.6.# 3.3.8 Security or Policy Status - x.7.#

Identifying Status Codes

SMTP status codes can be of a "regular" or "extended" variety, depending on the context of the error. Within an SMTP session, regular SMTP Status Codes are three-digit values that have various definitions depending on the value presented (e.g., 550). Regular SMTP status codes are properly referred to as server "reply codes".

Within a modern-day DSN message, a traditional SMTP reply code is supplemented by an additional status code that consists of three numerical fields separated by ( . ) dots/periods. This format of an SMTP status code is referred to as an Extended SMTP Status Code (e.g., 5.5.0). Extended SMTP status codes have a more granular definition to the errors that they represent than the traditional SMTP status codes because they are not only indicative of an individual server response, but also to the condition of the e-mail message transmittal itself. Each of the fields of an extended SMTP status code is referred to as a sub-code. Each sub-code denotes a different class of status, as well as an event and condition of the transmission.

Example DSN

Everything in the Delivery Status Notification (DSN) message is MTA-specific boilerplate, except for what is enclosed in angle brackets:

1. server.sendingdomain.tld
   The server sending the DSN message.
2. #4.2.1
   The three sub-code Extended SMTP Status Code.
3. smtp;550 4.2.1
   The server SMTP Status Code reply, with an appended Extended SMTP Status Code of the message status.
4. mailbox temporarily disabled: recipient@receivingdomain.tld
   The verbose status message to supplement the single SMTP Status Code.

SMTP Status Codes

• Abstracted from RFC 2821

The three digits of the reply each have a special significance. The first digit denotes whether the response is good, bad or incomplete. An unsophisticated SMTP client, or one that receives an unexpected code, will be able to determine its next action (proceed as planned, redo, retrench, etc.) by examining this first digit. An SMTP client that wants to know approximately what kind of error occurred (e.g., mail system error, command syntax error) may examine the second digit. The third digit and any supplemental information that may be present is reserved for the finest gradation of information.

There are five values for the first digit of the reply code. The second digit encodes responses in specific categories. The third digit gives a finer gradation of meaning in each category specified by the second digit. The list of replies illustrates this. Each reply text is recommended rather than mandatory, and may even change according to the command with which it is associated. On the other hand, the reply codes must strictly follow the specifications in this section. Receiver implementations should not invent new codes for slightly different situations from the ones described here, but rather adapt codes already defined.

Positive Preliminary reply - 1xx

The command has been accepted, but the requested action is being held in abeyance, pending confirmation of the information in this reply. The SMTP client should send another command specifying whether to continue or abort the action. Note: unextended SMTP does not have any commands that allow this type of reply, and so does not have continue or abort commands.

Positive Completion reply - 2xx

The requested action has been successfully completed. A new request may be initiated.

211 - System status, or system help reply

214 - Help message

Information on how to use the receiver or the meaning of a particular non-standard command; this reply is useful only to the human user

220 - <domain> Service ready

221 - <domain> Service closing transmission channel

250 - Requested mail action okay, completed

251 - User not local; will forward to <forward-path>

252 - Cannot VRFY user, but will accept message and attempt delivery

253 - OK, <messages> pending messages for node <node> started

Positive Intermediate reply - 3xx

The command has been accepted, but the requested action is being held in abeyance, pending receipt of further information. The SMTP client should send another command specifying this information. This reply is used in command sequence groups (i.e., in DATA).

354 - Start mail input; end with <CRLF>.<CRLF>

355 - Octet-offset is the transaction offset

Transient Negative Completion reply - 4xx

The command was not accepted, and the requested action did not occur. However, the error condition is temporary and the action may be requested again. The sender should return to the beginning of the command sequence (if any). It is difficult to assign a meaning to "transient" when two different sites (receiver- and sender-SMTP agents) must agree on the interpretation. Each reply in this category might have a different time value, but the SMTP client is encouraged to try again. A rule of thumb to determine whether a reply fits into the 4yz or the 5yz category (see below) is that replies are 4yz if they can be successful if repeated without any change in command form or in properties of the sender or receiver (that is, the command is repeated identically and the receiver does not put up a new implementation).

421 - <domain> Service not available, closing transmission channel

This may be a reply to any command if the service knows it must shut down

432 - A password transition is needed

450 - Requested mail action not taken: mailbox unavailable

e.g., mailbox busy

451 - Requested action aborted: local error in processing

452 - Requested action not taken: insufficient system storage

453 - You have no mail

454 - TLS not available due to temporary reason. Encryption required for requested authentication mechanism

458 - Unable to queue messages for node <node>

459 - Node <node> not allowed: <reason>

Permanent Negative Completion reply - 5xx

The command was not accepted and the requested action did not occur. The SMTP client is discouraged from repeating the exact request (in the same sequence). Even some "permanent" error conditions can be corrected, so the human user may want to direct the SMTP client to re-initiate the command sequence by direct action at some point in the future (e.g., after the spelling has been changed, or the user has altered the account status).

500 - Syntax error, command unrecognized

This may include errors such as command line too long

501 - Syntax error in parameters or arguments

502 - Command not implemented

503 - Bad sequence of commands

504 - Command parameter not implemented

521 - <machine> does not accept mail

530 - Must issue a STARTTLS command first. Encryption required for requested authentication mechanism

534 - Authentication mechanism is too weak

538 - Encryption required for requested authentication mechanism

550 - Requested action not taken: mailbox unavailable

e.g., mailbox not found, no access, or command rejected for policy reasons

551 - User not local; please try <forward-path>

552 - Requested mail action aborted: exceeded storage allocation

553 - Requested action not taken: mailbox name not allowed

e.g., mailbox syntax incorrect

554 - Transaction failed

Or, in the case of a connection-opening response, "No SMTP service here"

Extended SMTP Status Codes

• Abstracted from RFC 3463

The first sub-code or "Class Sub-Code" indicates the status of the delivery attempt. The second sub-code or "Subject Sub-Code" indicates the probable source of any delivery anomalies. The third sub-code or "Detail Sub-Code" provides specific detail or indicates a precise error condition and is defined relative to the subject of the "Subject Sub-Code".

Class Sub-Codes - #.x.x

The Class Sub-Code provides a broad classification of the delivery status.

2.x.x - Success

Specifies that the DSN is reporting a positive delivery action. Detail sub-codes may provide notification of transformations required for delivery.

4.x.x - Persistent Transient Failure

A failure in which the message as sent is valid, but some temporary event prevents the successful sending of the message. Sending in the future may be successful.

5.x.x - Permanent Failure

A failure 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.

Subject Sub-Codes - x.#.x

The Subject Sub-Code classifies the delivery status. This value applies to each of the three Class Sub-Code classifications. The Subject Sub-Code, if recognized, must be reported even if the additional detail provided by the detail of the Enumerated Status Code is not recognized.

x.0.x - Other or Undefined Status

There is no additional subject information available.

x.1.x - Addressing Status

The address status reports on the originator or destination address. It may include address syntax or validity. These errors can generally be corrected by the sender and retried.

x.2.x - Mailbox Status

Mailbox status indicates that something having to do with the mailbox has cause this DSN. Mailbox issues are assumed to be under the general control of the recipient.

x.3.x - Mail System Status

Mail system status indicates that something having to do with the destination system has caused this DSN. System issues are assumed to be under the general control of the destination system administrator.

x.4.x - Network and Routing Status

The networking or routing codes report status about the delivery system itself. These system components include any necessary infrastructure such as directory and routing services. Network issues are assumed to be under the control of the destination or intermediate system administrator.

x.5.x - Mail Delivery Protocol Status

The mail delivery protocol status codes report failures involving the message delivery protocol. These failures include the full range of problems resulting from implementation errors or an unreliable connection. Mail delivery protocol issues may be controlled by many parties including the originating system, destination system, or intermediate system administrators.

x.6.x - Message Content or Media Status

The message content or media status codes report failures involving the content of the message. These codes report failures due to translation, transcoding, or otherwise unsupported message media. Message content or media issues are under the control of both the sender and the receiver, both of whom must support a common set of supported content-types.

x.7.x - Security or Policy Status

The security or policy status codes report failures involving policies such as per-recipient or per-host filtering and cryptographic operations. Security and policy status issues are assumed to be under the control of either or both the sender and recipient. Both the sender and recipient must permit the exchange of messages and arrange the exchange of necessary keys and certificates for cryptographic operations.

Detail Sub-Codes - x.x.#

The following section defines and describes the Detail Sub-Code. This value provides more information about the status and is defined relative to the subject-code of the status.

Other or Undefined Status

x.0.0 - Other undefined Status

Other undefined status is the only undefined error code. It should be used for all errors for which only the class of the error is known.

Address Status - x.1.#

x.1.0 - Other address status

Something about the address specified in the message caused this DSN.

x.1.1 - Bad destination mailbox address

The mailbox specified in the address does not exist. For Internet mail names, this means the address portion to the left of the "@" sign is invalid. This code is only useful for permanent failures.

x.1.2 - Bad destination system address

The destination system specified in the address does not exist or is incapable of accepting mail. For Internet mail names, this means the address portion to the right of the "@" is invalid for mail. This codes is only useful for permanent failures.

x.1.3 - Bad destination mailbox address syntax

The destination address was syntactically invalid. This can apply to any field in the address. This code is only useful for permanent failures.

x.1.4 - Destination mailbox address ambiguous

The mailbox address as specified matches one or more recipients on the destination system. This may result if a heuristic address mapping algorithm is used to map the specified address to a local mailbox name.

x.1.5 - Destination address valid

This mailbox address as specified was valid. This status code should be used for positive delivery reports.

x.1.6 - Destination mailbox has moved, No forwarding address

The mailbox address provided was at one time valid, but mail is no longer being accepted for that address. This code is only useful for permanent failures.

x.1.7 - Bad sender's mailbox address syntax

The sender's address was syntactically invalid. This can apply to any field in the address.

x.1.8 - Bad sender's system address

The sender's system specified in the address does not exist or is incapable of accepting return mail. For domain names, this means the address portion to the right of the "@" is invalid for mail.

Mailbox Status - x.2.#

x.2.0 - Other or undefined mailbox status

The mailbox exists, but something about the destination mailbox has caused the sending of this DSN.

x.2.1 - Mailbox disabled, not accepting messages

The mailbox exists, but is not accepting messages. This may be a permanent error if the mailbox will never be re-enabled or a transient error if the mailbox is only temporarily disabled.

x.2.2 - Mailbox full

The mailbox is full because the user has exceeded a per-mailbox administrative quota or physical capacity. The general semantics implies that the recipient can delete messages to make more space available. This code should be used as a persistent transient failure.

x.2.3 - Message length exceeds administrative limit

A per-mailbox administrative message length limit has been exceeded. This status code should be used when the per-mailbox message length limit is less than the general system limit. This code should be used as a permanent failure.

x.2.4 - Mailing list expansion problem

The mailbox is a mailing list address and the mailing list was unable to be expanded. This code may represent a permanent failure or a persistent transient failure.

Mail system status - x.3.#

x.3.0 - Other or undefined mail system status

The destination system exists and normally accepts mail, but something about the system has caused the generation of this DSN.

x.3.1 - Mail system full

Mail system storage has been exceeded. The general semantics imply that the individual recipient may not be able to delete material to make room for additional messages. This is useful only as a persistent transient error.

x.3.2 - System not accepting network messages

The host on which the mailbox is resident is not accepting messages. Examples of such conditions include an immanent shutdown, excessive load, or system maintenance. This is useful for both permanent and permanent transient errors.

x.3.3 - System not capable of selected features

Selected features specified for the message are not supported by the destination system. This can occur in gateways when features from one domain cannot be mapped onto the supported feature in another.

x.3.4 - Message too big for system

The message is larger than per-message size limit. This limit may either be for physical or administrative reasons. This is useful only as a permanent error.

x.3.5 System incorrectly configured

The system is not configured in a manner which will permit it to accept this message.

Network and Routing Status - x.4.#

x.4.0 - Other or undefined network or routing status

Something went wrong with the networking, but it is not clear what the problem is, or the problem cannot be well expressed with any of the other provided detail codes.

x.4.1 - No answer from host

The outbound connection attempt was not answered, either because the remote system was busy, or otherwise unable to take a call. This is useful only as a persistent transient error.

x.4.2 - Bad connection

The outbound connection was established, but was otherwise unable to complete the message transaction, either because of time-out, or inadequate connection quality. This is useful only as a persistent transient error.

x.4.3 - Directory server failure

The network system was unable to forward the message, because a directory server was unavailable. This is useful only as a persistent transient error.

The inability to connect to an Internet DNS server is one example of the directory server failure error.

x.4.4 - Unable to route

The mail system was unable to determine the next hop for the message because the necessary routing information was unavailable from the directory server. This is useful for both permanent and persistent transient errors.

A DNS lookup returning only an SOA (Start of Administration) record for a domain name is one example of the unable to route error.

x.4.5 - Mail system congestion

The mail system was unable to deliver the message because the mail system was congested. This is useful only as a persistent transient error.

x.4.6 - Routing loop detected

A routing loop caused the message to be forwarded too many times, either because of incorrect routing tables or a user forwarding loop. This is useful only as a persistent transient error.

x.4.7 - Delivery time expired

The message was considered too old by the rejecting system, either because it remained on that host too long or because the time-to-live value specified by the sender of the message was exceeded. If possible, the code for the actual problem found when delivery was attempted should be returned rather than this code.

Mail Delivery Protocol Status - x.5.#

x.5.0 - Other or undefined protocol status

Something was wrong with the protocol necessary to deliver the message to the next hop and the problem cannot be well expressed with any of the other provided detail codes.

x.5.1 - Invalid command

A mail transaction protocol command was issued which was either out of sequence or unsupported. This is useful only as a permanent error.

x.5.2 - Syntax error

A mail transaction protocol command was issued which could not be interpreted, either because the syntax was wrong or the command is unrecognized. This is useful only as a permanent error.

x.5.3 - Too many recipients

More recipients were specified for the message than could have been delivered by the protocol. This error should normally result in the segmentation of the message into two, the remainder of the recipients to be delivered on a subsequent delivery attempt. It is included in this list in the event that such segmentation is not possible.

x.5.4 - Invalid command arguments

A valid mail transaction protocol command was issued with invalid arguments, either because the arguments were out of range or represented unrecognized features. This is useful only as a permanent error.

x.5.5 - Wrong protocol version

A protocol version mis-match existed which could not be automatically resolved by the communicating parties.

Message Content or Message Media Status - x.6.#

x.6.0 - Other or undefined media error

Something about the content of a message caused it to be considered undeliverable and the problem cannot be well expressed with any of the other provided detail codes.

x.6.1 - Media not supported

The media of the message is not supported by either the delivery protocol or the next system in the forwarding path. This is useful only as a permanent error.

x.6.2 - Conversion required and prohibited

The content of the message must be converted before it can be delivered and such conversion is not permitted. Such prohibitions may be the expression of the sender in the message itself or the policy of the sending host.

x.6.3 - Conversion required but not supported

The message content must be converted to be forwarded but such conversion is not possible or is not practical by a host in the forwarding path. This condition may result when an ESMTP gateway supports 8bit transport but is not able to downgrade the message to 7 bit as required for the next hop.

x.6.4 - Conversion with loss performed

This is a warning sent to the sender when message delivery was successfully but when the delivery required a conversion in which some data was lost. This may also be a permanant error if the sender has indicated that conversion with loss is prohibited for the message.

x.6.5 - Conversion Failed

A conversion was required but was unsuccessful. This may be useful as a permanent or persistent temporary notification.

Security or Policy Status - x.7.#

x.7.0 - Other or undefined security status

Something related to security caused the message to be returned, and the problem cannot be well expressed with any of the other provided detail codes. This status code may also be used when the condition cannot be further described because of security policies in force.

x.7.1 - Delivery not authorized, message refused

The sender is not authorized to send to the destination. This can be the result of per-host or per-recipient filtering. This memo does not discuss the merits of any such filtering, but provides a mechanism to report such. This is useful only as a permanent error.

x.7.2 - Mailing list expansion prohibited

The sender is not authorized to send a message to the intended mailing list. This is useful only as a permanent error.

x.7.3 - Security conversion required but not possible

A conversion from one secure messaging protocol to another was required for delivery and such conversion was not possible. This is useful only as a permanent error.

x.7.4 - Security features not supported

A message contained security features such as secure authentication which could not be supported on the delivery protocol. This is useful only as a permanent error.

x.7.5 - Cryptographic failure

A transport system otherwise authorized to validate or decrypt a message in transport was unable to do so because necessary information such as key was not available or such information was invalid.

x.7.6 - Cryptographic algorithm not supported

A transport system otherwise authorized to validate or decrypt a message was unable to do so because the necessary algorithm was not supported.

x.7.7 - Message integrity failure

A transport system otherwise authorized to validate a message was unable to do so because the message was corrupted or altered. This may be useful as a permanent, transient persistent, or successful delivery code.