skip to content

In SMTP, what do a reply code's first and second digits mean, and how does an enhanced status code such as 5.1.1 refine them?

level: juniorimportance: must knowfreq 60%

answer

  1. three digits, read left to right
  2. done, send more, retry, give up
  3. syntax, connection, mail system
  4. class.subject.detail after the code

basics

~20 s

An SMTP reply's first digit gives the outcome: 2 done, 3 send more, 4 temporary failure worth retrying, 5 permanent failure. The second digit names the category, and an enhanced code like 5.1.1 adds class, subject and detail.

solid answer

~50 s

Every SMTP reply starts with three digits (RFC 5321 4.2). The first is the one a client acts on: `2yz` completed, `3yz` intermediate (the `354` after `DATA` asks for the message text), `4yz` transient, so the identical command may succeed later, and `5yz` permanent, so it should not be repeated unchanged. The second digit is the category: `x0z` syntax, `x1z` information, `x2z` the connection, `x5z` the mail system. A server that advertises `ENHANCEDSTATUSCODES` (RFC 2034) prefixes the text of its 2xx, 4xx and 5xx replies with an RFC 3463 code, `class.subject.detail`, whose class must agree with the first digit: `550 5.1.1` is a permanent failure because the destination mailbox does not exist, while `452 4.2.2` reports a full mailbox as a temporary condition. A multiline reply puts a hyphen after the code on every line but the last.

go deeper

for a junior

Recall the four first digits: 2 done, 3 send more, 4 try again later, 5 do not repeat. Be able to say that 354 is the reply to DATA.

for a middle

Explain the second digit's categories, multiline replies with the hyphen, and how class, subject and detail in an enhanced code such as 5.1.1 narrow a bare 550.

for a senior

Read a log reply end to end and say which side must act: a 4.2.2 waits on the recipient's quota, a 5.7.1 on a policy, a 5.1.1 on the sender's address list.

for a principal

Argue for monitoring and alerting on enhanced codes rather than reply text, since text varies by server while codes are the stable contract, and say what that buys a mail team.

## Why SMTP replies are numbers SMTP (RFC 5321) is a lock-step dialog: the client sends a command, the server answers with a **reply** made of a three-digit **reply code** and some text. The text is for humans and may change from server to server; RFC 5321 4.2.1 calls each reply text "recommended rather than mandatory", while the codes "must strictly follow" the specification. Software therefore decides what to do from the digits alone, which is why an operator reading a log learns to read them first. ## The first digit: what the client does next | First digit | RFC 5321 name | What the client does | |---|---|---| | `2` | Positive Completion | the action is done; send the next command | | `3` | Positive Intermediate | send the information the server is waiting for | | `4` | Transient Negative Completion | the action did not happen; the same command may succeed later | | `5` | Permanent Negative Completion | the action did not happen; do not repeat it unchanged | The RFC's rule of thumb for choosing between 4 and 5: a reply belongs in `4yz` if the command could succeed when repeated **identically**, with nothing changed on either side. In core SMTP the only `3yz` reply is `354`, the answer to `DATA` that tells the client to send the message text. What a sending queue does over hours and days after a `4yz` or a `5yz` is a subject of its own, covered with submission and bounces. ## The second digit: which part of the system answered - `x0z` **syntax**: a malformed, unknown or unimplemented command (`500`, `501`, `502`, `503`, `504`). - `x1z` **information**: status and help (`211`, `214`). - `x2z` **connections**: the transmission channel (`220` greeting, `221` closing, `421` service not available). - `x5z` **mail system**: the mailbox or the transaction (`250`, `354`, `450`, `550`, `552`). - `x3z` and `x4z` are left unspecified by RFC 5321. The third digit is the finest gradation, and RFC 5321 asks servers to adapt the codes already defined rather than invent new ones. ## Multiline replies A reply can span several lines. Every line except the last carries the code followed by a **hyphen**; the last carries the code followed by a **space**. The answer to `EHLO` is the reply most people see in this form: 1. `S: 250-mail.example.com` 2. `S: 250-PIPELINING` 3. `S: 250-SIZE 10240000` 4. `S: 250 ENHANCEDSTATUSCODES` A client keeps reading until it sees the line with the space. Confusing those continuation lines with answers to separate commands is a classic client bug, and RFC 2920 forbids it for pipelined sessions. ## Enhanced status codes The three-digit code is coarse: `550` covers a mailbox that does not exist, a mailbox with no access and a policy refusal alike. **Enhanced status codes** (RFC 3463) add precision. The syntax is `class.subject.detail`: - **class** is `2`, `4` or `5`: success, persistent transient failure, permanent failure; - **subject** says which part failed: `X.1` addressing, `X.2` mailbox, `X.3` mail system, `X.4` network and routing, `X.5` the mail delivery protocol, `X.6` message content or media, `X.7` security or policy; - **detail** is the precise condition: `X.1.1` bad destination mailbox address, `X.2.2` mailbox full, `X.3.4` message too big for the system, `X.7.1` delivery not authorized. A server signals that it uses them by listing the `ENHANCEDSTATUSCODES` keyword in its `EHLO` response (RFC 2034). It then prefixes the text of every 2xx, 4xx and 5xx reply, except the greeting and the answer to `HELO` or `EHLO`, with an enhanced code; `3xx` replies carry none. RFC 2034 requires the class to **agree** with the first digit: a `5xx` reply carries a `5.X.X` code, a `4xx` reply a `4.X.X` code. ## Reading a reply as an operator 1. Read the first digit: is this done, waiting, temporary or permanent? 2. Read the second digit: is the complaint about syntax, the connection or the mail system? 3. Read the enhanced code, if present, for the subject and detail: `550 5.1.1` means the address does not exist; `452 4.2.2` means a full mailbox that may empty; `554 5.7.1` means a policy refusal. 4. Only then read the text, which may name the rule or the list that matched but is not part of the contract. RFC 3463 also asks clients that meet an unknown detail code to report the general meaning of its subject, so an unfamiliar detail under `5.1` is still read as a permanent addressing failure.

  • Why does a 354 reply carry no enhanced status code even on a server that advertises ENHANCEDSTATUSCODES?
    RFC 2034 attaches enhanced codes only to 2xx, 4xx and 5xx replies, apart from the greeting and the answer to `HELO` or `EHLO`. RFC 3463 defines just three classes, success, persistent transient failure and permanent failure, and an intermediate `354` ("send the message text") is none of them, so it goes out with its three-digit code alone.
  • How does a client tell one multiline reply from replies to several pipelined commands?
    By the character after the code: a hyphen means the reply continues, a space marks its last line. RFC 2920 tells a pipelining client to count complete replies and match that count to the commands it sent, and it explicitly forbids matching replies by their code value or text.

  • 4xx and 5xx replies both mean the message has bounced for good.
  • The reply text is the contract; the three digits are only decoration.
  • A 354 reply means the server has accepted and queued the message.
  • An enhanced code's class may differ from the basic reply's first digit.
  • The middle digit of 5.1.1 marks a temporary condition.