What SMTP Replies & Enhanced Status Codes Mean (& Why You Should Care)

It’s that time of year again.

That time where you may not be fully listening to your accountant. Sure, you can see her lips moving, but just can’t understand what she’s saying. You know it’s important and that it should matter—it’s your money, after all. But sometimes it’s easier to totally space out, especially when they start talking way over your head.

If you’ve ever worked with an accountant, you probably know what I’m talking about. Growing up with a Dad as an accountant, I was always aware of tax season. I would see clients in his office, carrying stacks of paper piled high, many with confused looks.  I could tell they were smart, successful people, but when it comes to high-level tax code, they simply couldn’t keep up. So unless they made an effort to understand, it was easy to start dissociating and daydreaming again.

Which got me thinking—a lot of email senders do the exact same thing with SMTP replies and enhanced status codes. Have you ever seen something like the following from an ISP in your email server’s logs?

421 4.7.0 [TS01] Messages from temporarily deferred –; see http://postmaster.yahoo.com/errors/421-ts01.html

I’m sure you have. But have you ever wondered what it means—what it is that the ISPs are trying to tell you? Or do you just ignore them and move on?

If you do, you are missing out. Like tax forms, these codes can be initially confusing, but invaluable to your email business and your long term results if you understand them (or have the help of an email expert that can point you in the right direction).

Unlocking The Mystery

Let’s take another look at the message quoted above and translate it into plain English. We selected this particular deferral message because it’s one of the more common ones that we see encountered when a server is having deliverability issues. Here it is again:

421 4.7.0 [TS01] Messages from temporarily deferred –; see http://postmaster.yahoo.com/errors/421-ts01.html

First, we can tell from this message that a mail server attempted to deliver an email to a Yahoo customer, and Yahoo’s mail servers issued a deferral. Deferrals essentially mean, “We can’t accept the message now, but please try again later.”

This can be broken up into three parts:

Message Part Content Meaning
Basic status code “421” “Service not available, closing transmission channel”
Enhanced status code “4.7.0” “Something related to security caused the message to be returned”
Reply text “[TS01] Messages from temporarily deferred –; see http://postmaster.yahoo.com/errors/421-ts01.html” The reply text field is optional and meant to be human-readable.

As you can see, there are two status codes. Why have both? To answer that question, we’ll have to take a little trip back through time.

A Tale of Two Status Codes

SMTP (the Simple Message Transfer Protocol), which is still used to deliver the vast majority of email today, is rapidly approaching its 35th birthday. Basic status codes were first defined in RFC 821, which was published back in 1982. At the time, they were simply called SMTP replies, since “enhanced status codes” weren’t invented yet. The idea was that an SMTP server should send one reply in response to every command issued by an SMTP client.

The basic status code is limited to three digits, and because of other requirements in the SMTP spec, there are actually only about 12 useful codes for delivery reports! As SMTP grew, multiple delivery failure reasons used the same code. Software sometimes produced an incorrect code and then clarified the meaning in the human-readable text. It was all kind of a mess.

The problems prompted the creation of enhanced status codes. Introduced in RFC 1893 (published in 1996), these codes use a series of 3 numbers using dotted decimal notation, allowing more options.

The enhanced status code does not replace the humble basic status code but adds to it. The basic status code, also called the SMTP Reply Code, is still a core part of the SMTP protocol and is used to communicate the success or failure of every SMTP command along with the many steps of delivering an email. The enhanced status code answers the larger question “tell me why my email delivery failed?”

Enhanced Status Codes Explained

Since enhanced status codes offer more granularity, it pays to look at them closely.

As we mentioned earlier, enhanced status codes consist of three numbers in dotted decimal notation. An enhanced status code’s first number is either a 2, 4 or 5:

Status code Description
2.x.y The message was delivered successfully.
4.x.y There was a persistent transient failure. This means this the message delivery failed due to a temporary failure. This initially causes the message to be deferred or tried again later. If it persists, then the message will eventually bounce.
5.x.y There was a permanent failure.

The status code’s second number defines the “subject,” or category, and the third number the detailed reason in that category.

The combination of the status code’s second and third numbers form the “enumerated,” or specific status code. The Internet Assigned Numbers Authority (IANA) maintains a registry of enhanced SMTP status codes that does an excellent job of summarizing the meanings of these enumerated status codes.

Going back to the status code in example deferral message “4.7.0”, the SMTP status code registry indicates that status codes of the form x.7.0 have a meaning of:

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.

So, in this case, even with the enhanced granularity that’s provided by enhanced status code, we’re still left with some ambiguity. Some of that ambiguity will be addressed in the upcoming “Deciphering the Reply Text” section.

Deciphering the Reply Text

Everything that follows the basic and enhanced status codes is considered to be the reply text. The reply text can be invaluable for messages like the one that we’re exploring in this blog post, which have status codes that lack specificity.

Unlike status codes, there are no standards for the content of reply text, so different ISPs craft their reply texts differently (and to varying degrees of helpfulness). Let’s take another look at our example reply text:

[TS01] Messages from temporarily deferred –; see http://postmaster.yahoo.com/errors/421-ts01.html

The codes [TS01] and are internal use codes that Yahoo has chosen to include, but they don’t really help us yet. And unfortunately, the link that’s provided in this deferral is broken as of April 2017. Argh. Luckily, Yahoo has an SMTP error code table that we can use to cross-reference the codes we’re seeing. At that page, Yahoo provides an English translation of 421 4.7.0 [TS01] :

We’re seeing unusual traffic patterns from your server. Submit your sending IPs for review.

Aha! Now we have our answer, as well as a possible solution.

This is why taking a closer look at deferral messages can really pay off. Sometimes you may have to track down documentation on your own if the link in the reply text is broken, but that’s a small price to pay to understand why the deferral is occurring and what you can do to fix it.

Keeping Your List Clean

One of your responsibilities as an email sender is to keep your list clean by removing undeliverable addresses.

Because the singularity hasn’t happened yet, we don’t yet have an artificial super-intelligence analyzing each bounce. But we do have the next best thing—GreenArrow’s bounce processor.

GreenArrow’s bounce processor applies a combination of rules that match known SMTP status codes and reply text strings, along with regular expressions to classify those bounces which aren’t an exact match. Here’s an example bounce:

552 5.2.2 <[email protected]>: Recipient address rejected: Cuota de correo excedida!!

The bounce processor, without knowing how to read Spanish, sees the Enhanced Status Code of “5.2.2” and know that this means “Mailbox full”. You don’t want this email address removed from your mailing list unless GreenArrow’s bounce processor discovers that this mailbox is always full (which it is smart enough to do.)

Another example:

550 5.1.1 <[email protected]>: Recipient address rejected: example.com.ar

The human-readable text says “Recipient address rejected,” but gives no reason as to why. The definitive reason is in the Enhanced Status Code of “5.1.1” which means: “Bad destination mailbox address.” This is an address you want to stop sending to!

Just one more example:

451 4.3.2 Please try again later

The code “4.3.2” means “System not accepting network messages” and “Examples of such conditions include an immanent shutdown, excessive load, or system maintenance.” This is telling you that the receiving system is having internal problems.

To deactivate or not to deactivate? That is the question…

As you can imagine, correctly classifying the different types of bounces that can occur, and determining whether a given bounce should cause a subscriber to be deactivated, can be tricky. The SMTP status codes themselves are easy to parse, but unfortunately, they don’t always provide the level of detail needed to determine exactly what kind of bounce occurred. They also sometimes contain contradictory information.

Here is an example:

554 5.7.1 [P4] Message blocked due to spam content in the message.

Let’s break this down:

  • The basic status code of “554” is a bounce, which means “Transaction failed” according to RFC 5321. That’s accurate, but not terribly precise.
  • The enhanced status code of “5.7.1” means “The sender is not authorized to send to the destination. This can be the result of per-host or per-recipient filtering”, according to RFC 3463. We’re getting closer!
  • The reply text of “[P4] Message blocked due to spam content in the message” tells us what happened with the most specificity (something about the message’s content triggered a spam filter).

As you can see, we get more specific as we drill down from the basic status code to the enhanced status code to the reply text.

In this example, GreenArrow’s bounce processor will categorize this bounce as type 52, meaning “Mail block – Spam detected.” This bounce code indicates the email could not be delivered but does not actually provide any indicators that the email address itself is bad. Because of this, the bounce processor logs the bounce in GreenArrow’s stats but doesn’t take any steps to deactivate the subscriber.

If this were a bounce containing information which indicated that the recipient’s email address was actually bad, GreenArrow’s bounce processor would execute whatever actions it’s configured to (in most cases, deactivate the subscriber).

Code speaks; listen to it

Numbers and codes by themselves are boring—that is, until you understand what they’re saying. Sure, most accountants will never come close to holding your rapt attention, but you have a much better chance of saving money when you listen (and apply) what they’re telling you. And like a good accountant, GreenArrow can help improve your deliverability by making the right decisions based on the SMTP replies and enhanced status codes you’re already receiving.

If reading this is making you wonder whether your bounce processor is making the right call, we’d love to show you what GreenArrow can do for your business. Contact us today for a free demo and see for yourself what we can do. In the meantime, keep calm and code on!

Appendix—Useful resources

Here are some resources that I found to be invaluable when writing this blog post. They’re also handy when analyzing the SMTP status codes returned for bounces and deferrals:

  • IANA’s SMTP Enhanced Status Codes Registry aggregates and links to information that was originally published in a number of RFCs. The code registry was first proposed in RFC 5248. Very meta.
  • RFC 5321 defines the Simple Mail Transfer Protocol (SMTP) and basic status codes.
  • RFC 3463 defines enhanced status codes.
  • RFC 3886 defines Delivery Status Notifications (DSN) and Message Disposition Notifications (MDN) response codes.

Don't Miss Out!

Sign up for the GreenArrow newsletter, and we’ll email you tips, updates, and resources.