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 provide your server name, SMTP port, username and password and the SMTP server then sends emails on your behalf and takes care of email deliverability.
However, SMTP errors can prevent your emails from getting delivered. And when these problems occur, it’s difficult to understand the cryptic error codes in your delivery reports. In this article, you’ll learn how to read common SMTP response codes and how you can troubleshoot delivery errors.
Looking for an SMTP service?
Learn more about MailerSend’s SMTP relay.
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. These numerical codes indicate a status or error pertaining to a message transmission, allowing senders to troubleshoot sending issues.
The following diagram shows the relationship between the SMTP client and server in the mail delivery process.
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.
A response to the HELP command that usually includes a link or URL to the FAQ page.
SMTP Service ready
The receiving server is ready for the next command.
Service closing transmission channel
The receiving server is closing the SMTP connection.
2.7.0 Authentication succeeded
The sending server’s authentication is successful.
Requested mail action okay, completed
Success! The email was delivered.
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.
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.
Reponse to email authentication AUTH command when the authentication method is accepted
Authentication has been successful.
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.
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.
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.
Requested action aborted: error in processing
The receiving server is unable to process the message due to email authentication rules. For example, if Sender Policy Framework (SPF) is being used, you should confirm that a DNS lookup can be made for your sending domain and that the domain’s name server is functioning properly.
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.
Server unable to accommodate the 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 not try again unless the problem is fixed.
The 500 series starts with errors in issuing SMTP commands like the following examples:
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.
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.
Command not implemented
The command is currently not supported on the receiving server. Review your sending commands as well as your MTA’s configuration.
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.
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.
Server does not accept mail
The server does not receive or send mail. This may be because the server is part of a mail relay. The email may fail or be relayed to another mail server. Check if the email has been delivered to confirm.
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.
Authentication credentials are invalid
There is an issue with client authentication with the email server. This may be because of incorrect credentials, invalid authentication methods, or invalid encryption settings.
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 to put you on their safelist.
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 MailerSend's inbuilt feature.
Error code 550 is sometimes used as a generic error code and it can also appear as 550 Blocked error or 550 Invalid recipient depending on the server's configuration. If you get the blocked error message, check to see if your IP address is in a blocklist.
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.
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.
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.
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.
Bonus: 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 make things more complicated, 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:
Positive Completion Reply
The requested action has been successfully completed.
Positive Intermediate Reply
The command is accepted but more information is needed before proceeding.
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.
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:
Responses about commands or parameters.
Responses to requests for more information.
Responses about the transmission channel.
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, [184.108.40.206]
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:
The requested mail action is okay and completed.
Persistent Transient Failure
Temporary conditions will cause the message to be delayed or abandoned.
The message in its current form cannot be delivered.
The second digit identifies the subject of the SMTP reply code:
Other or Undefined Status
Mail System Status
Network and Routing Status
Mail Delivery Protocol Status
Message Content or Media Status
Security or Policy Status
Finally, the third digit provides more detail and depends 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, but the address of the recipient at the server has also been accepted.
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!
Looking for an email service that makes SMTP super simple?
Sign up to MailerSend for free to start using our SMTP relay, webhooks, advanced email editors and more.