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:
These replies refer to syntax errors, syntactically correct commands that do not fit any functional category, and unimplemented or superfluous commands.
These are replies to requests for information, such as status or help.
These are replies referring to the transmission channel.
Yep, super-helpful – thanks RFC!
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
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 [18.104.22.168] 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 [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.