SMTP error codes

The codes#

Each page quotes the RFC that defines the code and the words Gmail, Outlook and Yahoo use for it on their own error pages, with links to what we read. Where a provider does not list a code, we say so instead of guessing. More codes are added as each page is checked, and each release is noted in the changelog.

How to read a code#

A reply such as 550 5.1.1 No such mailbox here has three parts. The first number is the basic reply code from RFC 5321: a 2 means done, a 4 means a temporary failure the client may try again, and a 5 means the client should not repeat the same request ^[1].

The second, 5.1.1, is the enhanced status code from RFC 3463: class, subject and detail ^[2]. The class repeats the first digit. The subject says where the problem is: 1 is the address, 2 the mailbox, 3 the receiving system, 4 the network, 5 the mail protocol, 6 the message content and 7 security or policy. IANA keeps the registry of details, and which basic codes each one goes with ^[3]. Some providers use details outside the registry, such as Microsoft's 550 5.7.515, so the text after the codes is always worth reading.

How Mailbay reports them#

• On mail you send. A temporary code makes the recipient deferred while our mail server retries; a permanent one makes it bounced. Each change emits an event with the server's reply in response, delivered to your webhooks.
• Suppression. Codes that mean the address does not exist, such as 550 5.1.1, add it to the project's suppression list. Policy refusals do not.
• Our own servers. Mailbay's receiving and submission servers answer with these codes too, each with a reason you can act on, like 535 5.7.8 for a key that does not exist. Mailbay's API errors are listed separately on the errors page.
• Authentication. Most policy refusals today come down to SPF, DKIM and DMARC, explained record by record in SPF, DKIM and DMARC explained.