What are SMTP codes and how to troubleshoot them
Simple Mail Transfer Protocol (SMTP) is the standard communication protocol for sending emails over the Internet.
Getting started with SMTP for your transactional emails is quick and easy. You simply provide your server name, port, username and password. The SMTP server then sends emails on your behalf and takes care of email deliverability.
However, when an SMTP error prevents your emails from getting delivered, it can be difficult to understand its cryptic error codes in your delivery reports. Read on to learn how to read common SMTP response codes and how you can troubleshoot delivery errors.
What are SMTP codes
SMTP response codes are updates sent by an SMTP server during the mail delivery process. Using a 3-digit format, they are sent in response to commands issued by an SMTP client. The following diagram shows the relationship between the SMTP client and server in the mail delivery process.
How to read SMTP codes
The SMTP specification defined basic status codes that were published in 1982. Because the codes were originally designed to report on the outcome of an SMTP command, their lack of detail made them unsuitable for delivery reports.
To compound the problem, some servers would assign the same error code to different delivery failures. Others would assign a code that only explained its meaning in the text description. Inconsistent application of the codes meant it was difficult to resolve mail sending issues!
Enter the enhanced status codes. They extend the basic status codes by providing more detail about the cause of the email delivery failure. Similarly, they also consist of 3-digit numbers separated by decimals. Let’s take a look at how to read them next.
Basic status codes
The first digit of a basic status code tells the sending server whether the response is good, bad or incomplete:
2: Positive Completion Reply. The requested action has been successfully completed.
3: Positive Intermediate Reply. The command is accepted but more information is needed before proceeding.
4: Transient Negative Completion Reply. The command was not accepted and no action was taken. This error is seen as temporary (soft bounce) and the sender can try again later.
5: Permanent Negative Completion Reply. The command was not accepted and no action was taken. This is a permanent error (hard bounce) and the sender should not repeat the command.
The second digit puts the SMTP response into a specific category:
0: Syntax. Responses about command or parameters.
1: Information. Responses to requests for more information.
2: Connections. Responses about the transmission channel.
5: Mail system. Responses about the status of the receiving mail server.
The third digit goes into more detail within the response category.
For example, if you telnet to MailerSend’s SMTP server and introduce yourself with the HELO command, you will see the following exchange:
HELO mailersend.net 250 smtp.mailersend.net Nice to meet you, [126.96.36.199]
The 250 response code means that it is a positive completion reply about the status of the mail system, i.e. the SMTP server has acknowledged your IP address and is waiting for your next command.
Enhanced status codes
Like the basic status codes, the first digit defines the class to which the code belongs:
2: Success! The requested mail action is okay and completed.
4: Persistent Transient Failure. Temporary conditions will cause the message to be delayed or abandoned.
5: Permanent Failure. The message in its current form cannot be delivered.
The second digit identifies the subject of the SMTP reply code:
0: Other or Undefined Status
1: Addressing Status
2: Mailbox Status
3: Mail System Status
4: Network and Routing Status
5: Mail Delivery Protocol Status
6: Message Content or Media Status
7: Security or Policy Status
Finally, the third digit provides more detail and it is dependent on the class and the subject.
For example, if you specify the recipient of the email with the RCPT TO command, the SMTP server may respond with 250 2.1.5 Recipient OK. This code means that not only is your command successful, the address of the recipient at the server has been accepted as well.
Common SMTP codes and how to troubleshoot them
The current SMTP standard defines the response codes but they are applied differently between SMTP servers. Not every mail server is configured in the same way and thus there will be differences in how mail delivery failures are interpreted.
General SMTP status codes
SMTP codes that start with 2 and 3 are general status messages that are sent in reply to requests from the sending server. They do not indicate errors in the mail delivery but are used as prompts in the exchange between the mail servers.
214 Help message. A response to the HELP command that usually includes a link or URL to the FAQ page.
220 SMTP Service ready. The receiving server is ready for the next command.
221 Service closing transmission channel. The receiving server is closing the SMTP connection.
235 2.7.0 Authentication succeeded: The sending server’s authentication is successful.
250 Requested mail action okay, completed. Success! The email was delivered.
251 User not local; will forward to <forward-path>. The receiving server doesn’t recognize the recipient but it will forward it to another email address.
252 Cannot VRFY user, but will accept message and attempt delivery. The receiving server doesn’t recognize the recipient but it will try to deliver the email anyway.
354 Start mail input. The email “header” has been received, the server is now waiting for the “body” of the message.
Temporary SMTP error codes
SMTP 400 codes are transient errors and are usually related to issues at the receiving mail server. Messages are returned as a soft bounce and the sender may try again after, for example, reducing the size of the attachments in the email.
421 Service not available, closing transmission channel. The receiving server or sending server is not reachable but another mail delivery will be attempted. If you are using a remote server like MailerSend's SMTP relay to send emails, test that you can connect to it successfully. Otherwise, you may wish to check the receiving server’s availability.
450 Requested mail action not taken: mailbox unavailable. This error could mean that the recipient does not exist, the mailbox does not have permission to receive the email, or the message was rejected due to a blocklist or filter.
To fix this, you should confirm the recipient’s email address, see if your IP address is on a blocklist, test your email for spam-like content, or try sending an email without an attachment.
451 Requested action aborted: error in processing. The receiving server is unable to process the message due to email authentication rules. If Sender Policy Framework (SPF) is being used, for example, you should confirm that a DNS lookup can be made for your sending domain and that the domain’s name server is functioning properly.
452 Requested action not taken: insufficient system storage. The receiving server is overwhelmed by too many messages being sent at once, or is out of memory or storage space. Review your sending rate by looking at your mail sending queue and logs, or inform the server’s mail administrator about the storage and free memory issues.
455 Server unable to accommodate parameters. The server cannot process the command at this time. You can retry after waiting a while or contact the receiving server’s mail administrator if the error persists.
Permanent SMTP error codes
SMTP 500 reply codes are mail delivery errors of a permanent nature that are usually caused by the sender. The receiving server returns the message as a hard bounce and prefers that the sender does not try again unless the problem is fixed.
The 500 series starts with errors in issuing SMTP commands like the following examples:
500 Syntax error, command unrecognized. The receiving server does not recognize the command. If your server is using antivirus or firewall software, try disabling them before sending the message again.
501 Syntax error in parameters or arguments. The command is recognized but there are errors with its options or command arguments. This server error is sometimes returned for an invalid or incorrect email! But it may be due to your antivirus or firewall software as well.
502 Command not implemented. The command is currently not supported on the receiving server. Review your sending commands as well as your MTA’s configuration.
503 Bad sequence of commands. The receiving server recognizes the command but its parameters or options are in the wrong sequence. This sometimes appears when the email account is not authenticated. Do review your MTA’s configuration as well.
504 Command parameter not implemented. Similar to 502, the command is recognized but its parameters or options are not supported on the receiving server. You may wish to review your sending commands as well as your MTA’s configuration.
The SMTP error codes then get more serious, like being suspected of sending spam or appearing in a blocklist. As an email sender, you should pay attention to the following codes because they can affect your sending reputation and email deliverability.
541 The recipient address rejected your message. The mail from the sender has been flagged as spam or blocked by the receiving server’s rules. Find out if your IP address is in a blocklist and scan your emails for content that could trigger spam filters. If you’re clear, ask the administrator of the server nicely to put you on their safelist.
550 Requested action not taken: mailbox unavailable. The recipient’s email address does not exist. Verify the email address by making sure it is free of typos or use an email verification tool like MailerCheck.
551 User not local; please try <forward-path>. The recipient was not found on the server but the message will be forwarded to another email. Used for spam prevention, this error is shown when you are not authorized to relay mail through the server. Review your authentication records to see if you can use an SMTP relay.
552 Requested mail action aborted: exceeded storage allocation. The user’s mailbox is full! Besides waiting for messages to be deleted, you can try to contact them through other means and inform them that their inbox is full.
553 Requested action not taken: mailbox name not allowed. The recipient cannot be found due to errors in the email address. Check that the email addresses are correct in the To, Cc and Bcc fields.
554 Transaction failed. This is bad news! The receiving mail server will not accept your message because, for example, you’re on a blocklist. Confirm whether your IP address appears in a blocklist. If you’re good, send a request to the receiving server to put your IP in their safelist.
SMTP response codes deciphered
SMTP plays a critical role in the email infrastructure of the Internet. It’s easy to implement it in your technology stack, but when things go wrong it’s hard to decipher what those SMTP codes mean. Here’s a tip: Bookmark this page and return to it whenever you encounter one!
What are the most common SMTP error codes that you’ve come across? Tell us about it below!