SMTP response codes
Every SMTP reply starts with a three-digit code. Most rejections also carry an enhanced status code from RFC 3463, such as 5.7.1, which names the kind of problem. Handle replies by these codes. The reply text explains the reason to a person and can change.
Temporary and permanent failures
The first digit tells you what to do next:
| Code | Meaning | What to do |
|---|---|---|
2xx | Success | Nothing. Lettermint accepted the command or the message. |
4xx | Temporary failure | Keep the message and retry later. |
5xx | Permanent failure | Do not retry the same message. Fix the cause, then resend it. |
Most SMTP libraries and mail servers queue and retry a 4xx reply for you. If your code sends with a raw SMTP client, add a retry with a backoff of a few minutes. A retry of a 5xx reply fails again with the same reply.
If you send an Idempotency-Key header, keep the same key when you retry after a 4xx reply. Lettermint then accepts the message only once.
Accepted messages
Lettermint replies 250 after the final . of the message when it accepts the message for delivery. The reply contains the Lettermint message ID, which you can look up in the dashboard and which webhook events use:
Code
A message with an X-LM-Scheduled-At header gets the schedule in UTC:
Code
Authentication
| Reply | Cause | What to do |
|---|---|---|
235 2.7.0 Authentication successful | Lettermint accepted the Project API token. | Nothing. |
535 5.7.8 | Lettermint did not accept the login. | Check that the password is a valid Project API token (not a Team API token), that SMTP is enabled for the project, and that the token's IP allowlist includes your server's address. |
454 4.7.0 Authentication service temporarily unavailable. Please try again. | Lettermint could not check the token. | Retry later. |
530 Authentication required | The client sent MAIL FROM or DATA before it logged in. | Turn on SMTP authentication in your client. |
504 Encryption required for requested authentication mechanism | The client tried to log in before it started TLS. | Use STARTTLS or a port with implicit TLS. See available ports. |
504 Unrecognized authentication type | The client asked for a mechanism other than PLAIN or LOGIN. | Select PLAIN or LOGIN. |
421 ... Too many authentication failures, closing transmission channel | One connection failed to log in too many times. Lettermint closes it. | Fix the credentials before you connect again. |
Sender and recipients
Lettermint checks the sender when your client sends MAIL FROM and each recipient when it sends RCPT TO. A rejected recipient does not stop the other recipients of the message.
| Reply | Cause | What to do |
|---|---|---|
550 The sending domain example.com is not verified. See: ... | The envelope sender uses a domain that is not verified for your team. | Verify the domain, or send from a verified domain. |
550 The sending domain example.com is not available for this project. See: ... | The domain is limited to other projects. | Send from a domain this project may use. |
550 Recipient ... not in team. Unverified teams can send mail only to team members. ... | Your team is not verified yet, and the recipient is not a team member. | Send to team members until your team is verified. |
550 Maximum of 50 recipients allowed per email. ... | The message already has 50 recipients. | Split the message, or use the batch endpoint. See Sending limits. |
501 Invalid MAIL FROM address or 501 Invalid RCPT TO address | The address syntax is invalid. | Correct the address. |
Rejected messages
Lettermint checks the message after the final . of DATA. A rejection there applies to the whole message and all its recipients.
| Reply | Cause | What to do |
|---|---|---|
550 5.7.0 | Your team reached its monthly email limit or its overage spending limit. | Upgrade your plan or raise the spending limit in the billing settings, then resend. |
550 5.7.0 | The Idempotency-Key was already used for a message with different content. | Send the new message with a new key. |
550 5.7.1 | The From domain is not verified, or it is limited to other projects. | Send from a verified domain this project may use. |
550 5.7.1 | The recipient is not allowed, because an unverified team can only send to its own members. | Send to team members until your team is verified. |
550 5.7.1 | The feature is not on your plan, for example scheduled delivery or a Sandbox project on the Free plan. | Upgrade your plan, or remove the header that uses the feature. |
550 5.7.1 | The Project API token is no longer valid for this project. | Log in again with a valid Project API token. |
553 5.1.3 | A recipient address in To or Cc, an envelope recipient, or a Lettermint test address is invalid. | Correct the address. |
553 5.1.7 | The From header is missing or invalid, or a Reply-To address is invalid. | Correct the address. |
552 5.3.4 | The message is over 25 MB as Lettermint counts it. | Make the message smaller. See Message size. |
550 5.5.3 | A Sandbox message has more recipients than Sandbox accepts per minute. | Send it to fewer recipients per message. |
550 5.6.0 | The content is invalid. Examples are a missing body, duplicate From or Reply-To headers, an invalid Message-ID, an invalid X-LM-* or X-Lettermint-* header value, an attachment that cannot be decoded, an invalid schedule, and an unknown route in X-Lettermint-Route. | Read the reply text, fix the message, and resend it. |
451 4.7.0 | The Sandbox rate limit is reached, or another message with the same Idempotency-Key is still being processed. | Retry later. |
451 4.3.0 | Lettermint had a temporary error. | Retry later. |
The reply text normally gives the exact reason. A reason that links to a site other than Lettermint is shortened to Message rejected. The code still tells you which row applies.
Custom headers lists the rules for each X-LM-* and X-Lettermint-* header.
Other replies to DATA
| Reply | Cause | What to do |
|---|---|---|
451 Bare line-feed in DATA; lines must end with CRLF. See: ... | A line of the message ends with LF instead of CRLF. Lettermint closes the connection. | Send CRLF line endings. See Line endings. |
550 Too many received headers - possible mail loop | The message has more than 100 Received headers. | Check your mail setup for a forwarding loop. |
452 Insufficient system storage | Lettermint cannot store the message right now. | Retry later. |
451 Temporary failure, please retry | Lettermint could not finish checking the attachments. | Retry later. |
Message size
The maximum message size is 25 MB, including headers, body, and attachments in their encoded form.
| Reply | Cause |
|---|---|
552 Message size exceeds fixed maximum message size | The client announced a size over 25 MB with the SIZE parameter of MAIL FROM. |
552 Message too big! | The message grew over 25 MB while the client sent it. |
552 5.3.4 | The body and attachments are over 25 MB when Lettermint counts the attachments in base64. This happens when the message sends attachments without base64 encoding. |
Do not retry these messages. Link to large files instead of attaching them. See Sending limits.
Attachments
Lettermint rejects messages with blocked attachment types with 550 5.7.1. The reply text names the reason:
Code
Lettermint also looks inside archives such as .zip files. It rejects an archive that contains a blocked file or that cannot be inspected safely. The reply then starts with 550 5.7.1 Message contains, followed by the reason.
Remove or replace the attachment, then resend the message. Sending limits lists every blocked file type.
Rate limits and Sandbox
Your plan quota and spending limit apply to SMTP sends. Reaching them gives the permanent 550 5.7.0 reply. Resend after you upgrade, raise the limit, or your usage period renews.
Sandbox projects accept up to 100 recipients per team per minute. Over that limit, Lettermint replies with a temporary failure:
Code
Retry after a minute.