SMTP Reply, Status and Error Codes

SMTP reply, status and error codes can often seem confusing, and the description provided (along with a 3-digit code), inconsistent. This overview post is designed to describe the structure of SMTP reply codes, how to interpret them, typical scenarios where you might encounter common reply codes, and finally, share a live example. For a deeper understanding, or to get the source information, please refer to RFC 5321.

 

Reply Code Structure

Firstly, there isn’t really anything in SMTP that is known as either a ‘status code’ or an ‘error code’. They’re all just reply codes, and some of these reply codes represent temporary or permanent errors – it’s a small, but important, nuance.

A reply code is 3-digits followed by a descriptive string, and each digit represents an important(ish) piece of information:

• The first digit represents the reply code ‘family’ and, broadly speaking, an SMTP client can assess the required follow-up action purely based on this first digit;
• The second digit provides a deeper indication of why the family code was returned; and
• The third digit is largely seen as ‘product specific’ and provides even finer detail, if so implemented.

An example reply code could be: 453 try again later.

Let’s explore each of the digits and their meaning a little deeper, and why the text is inconsistent between implementations.

 

The First Digit

This represents the family or class of the reply code, and there are only four valid values for the first digit (these descriptions have been lifted straight from RFC 5321):

2: Positive Completion reply
The requested action has been successfully completed. A new request may be initiated.

3: Positive Intermediate reply
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).

4: Transient Negative Completion reply
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 SHOULD try again. A rule of thumb to determine whether a reply fits into the 4 or the 5 category (see below) is that replies are 4 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).

5: Permanent Negative Completion reply
The command was not accepted and the requested action did not occur. The SMTP client SHOULD NOT repeat 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 reinitiate 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).

 

The Second Digit

The second digit encodes responses in specific reply codes families or classes. Those specified in RFC 5321 are:

0: Syntax
These replies refer to syntax errors, syntactically correct commands that do not fit any functional category, and unimplemented or superfluous commands.

1: Information
These are replies to requests for information, such as status or help.

2: Connections
These are replies referring to the transmission channel.

3: Unspecified
Yep, super-helpful – thanks RFC!

4: Unspecified
Again, super-helpful!

5: Mail system
These replies indicate the status of the receiver mail system vis-a-vis the requested transfer or other mail system action.

 

The Third Digit

The RFC does not specify what should, or even can, be returned in the third digit. It’s entirely the call of the implementor as to what to return that might be useful for that specific software. However, it must be between 0 and 9.

 

The Reply Text

The reply text may be longer than a single line and what it says can be at the implementors discretion. The RFC says that the total length of the line, including the 3-digit reply code and the carriage return and line feed is 512 bytes, so in practice this gives you 506 bytes of characters to explain the nature of the reply code.

Now you can see why the description is very inconsistent; there is no prescribed reply text and it is completely up to the implementor as to the information they return.

It is possible, under the RFC, to return multiline replies. To do this you are required to return that every line, except the last, begin with the reply code, followed immediately by a hyphen, “-” (also known as minus), followed by text. The last line will begin with the reply code, followed immediately by <SP>, optionally some text, and a carriage return and line feed.

A multiline reply text example:

250-First line
250-Second line
250-234 Text beginning with numbers
250 The last line

 

Pre-specified Reply Codes

RFC 5321 does specify some reply codes. These are listed here, but this is not an exhaustive list and you will undoubtedly come across others in your SMTP travels:

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

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

421 <domain> Service not available, closing transmission channel (this may be a reply to any command if the service knows it must shut down)

450 Requested mail action not taken: mailbox unavailable (e.g. mailbox busy or temporarily blocked for policy reasons)

451 Requested action aborted: local error in processing

452 Requested action not taken: insufficient system storage

455 Server unable to accommodate parameters

500 Syntax error, command unrecognised (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

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”)

555 MAIL FROM/RCPT TO parameters not recognised or not implemented

 

An Example

Here is an example of a real SMTP session, with the reply codes and text highlighted in red, lifted from our SMTP 101 blog post.

For fun, see if you can match the first, second and third digits to anything described above, for example, on line 11, the reply code is 334. So this means “successful pending more information”, which means “ok, we’ve started the authentication process, but I need more details to proceed”.  What other codes can you interpret?

250 HELP
EHLO EXAMPLE
250-us11-012mrc.dh.atmailcloud.com Hello 27-33-184-51.static.tpgi.com.au [27.33.184.51]
250-SIZE 52428800
250-8BITMIME
250-PIPELINING
250-AUTH LOGIN PLAIN
250-CHUNKING
250 HELP
AUTH PLAIN
334 
AHNvbWV1c2VyQGV4YW1wbGUuYXRtYWlsY2xvdWQuY29tAG15XlBhc3N3MHJk
235 Authentication succeeded
MAIL FROM: [email protected]
250 OK
RCPT TO: [email protected]
250 Accepted Recipient
DATA
354 Enter message, ending with "." on a line by itself
From: [email protected]
To: [email protected]
Subject: Hello everyone!

A little spoofed message from someone pretending to be the pre[email protected]

I hope you enjoyed this blog post.
.
250 OK id=1g0eWC-0003vH-Su
QUIT
221 Bye

 

 

Find this SMTP post useful?

We’re taking ideas for future how-to posts about the behind-the-scenes workings of email services. If you’d like to make a request, we invite you to drop us a line here.

Meanwhile, we invite you to check out some of our other how-to posts:

• IMAP 101: Manual IMAP Sessions
• IMAP Commands
• Advanced IMAP
• POP 101: Manual POP Sessions
• SMTP 101: Manual SMTP Sessions
• CalDAV and CardDAV

 

New to atmail?

atmail is an email solutions company with more than 20 years of global, white label, email expertise. You can trust us to deliver an email platform that is secure, stable and scalable. We power more than 170 million mailboxes worldwide and offer modern, white-labelled, cloud hosted email with your choice of US or (GDPR compliant) EU data centres. We also offer on-premises webmail and/or mail server options. To find out more, we invite you to enquire here.