SMTP errors and related Webhooks

The article provides insights into SMTP error codes and the associated automatic Webhook messages sent in case of an email delivery failure.

Sometimes, when an email fails to be delivered to the user, we receive an error code from the mail provider. This code is decoded, and an automatic Lost Webhook message is sent to inform you of possible reasons for the delivery failure.

Overview of the SMTP error code structure

The SMTP error code consists of three digits, each signifying distinct information.

  • The first digit indicates whether your request was accepted and processed:

    • 1 – The server received the command but awaits confirmation; the command has not been processed yet;
    • 2 – Successful execution of the action, and the server is ready to accept new commands;
    • 3 – The server received the command, but additional information is required for completion;
    • 4 – Temporary failure. Retry the command;
    • 5 – The server encountered an unrecoverable error, and your command will not be processed.
  • The second digit of the SMTP error code determines the functional category of the response:

    • 0 – Syntax error: correct commands with incorrect syntax, unrealized, or redundant commands;
    • 1 – Responses to information requests;
    • 2 – Responses related to the transmission channel;
    • 3 and 4 – Undefined;
    • 5 – Indicates the state of the mail server or system.
  • The third digit in the response code provides more detailed information about the delivery status.

Mapping SMTP error codes to Webhook explanations

In the table below, you'll find the most common error codes, their reasons as indicated in the automatic Webhook message, and a brief explanation.

SMTP Error CodeWebhookExplanation
452account_over_quotaThe command was canceled because the mail provider's server has insufficient system memory. Consider sending the email from another server.
454relay_access_deniedAuthentication is not possible due to a temporary failure on the server.
500message_rejectedThe server did not recognize the command due to incorrect syntax (e.g., a too-long command line).
511no_mailboxThe command was not executed because the mailbox or email address of the recipient was not found. Such a mailbox does not exist or has been deleted. The recipient's address may be entered incorrectly or contain errors.
540account_suspendedThe execution of the command was stopped due to the suspension or blockage of the email account on the mail service provider's server. This may be due to exceeding limits or violating usage rules.
550does_not_existThe command was not executed due to an unavailable mailbox of the user or rejection by the server due to suspicion of spam.
552user_over_quotaThe email was not sent due to a lack of space in the recipient's mailbox.
553user_not_exists_or_domain_is_not_allowedThe execution of the command was stopped because the mailbox with the specified name was not found.
554address_rejectedThe mail server rejected your email. Possible reasons include the server categorizing it as spam, detecting your IP address on a blacklist, or adding it to its own blacklist.