# 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](/platform/emails/idempotency), 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:

```text
250 Message accepted for delivery id=0199a5f2-7c1e-7d3a-9b2f-3c4d5e6f7a8b
```

A message with an [`X-LM-Scheduled-At` header](/platform/emails/scheduling) gets the schedule in UTC:

```text
250 Message accepted for delivery; scheduled for 2026-08-25T07:00:00Z id=0199a5f2-7c1e-7d3a-9b2f-3c4d5e6f7a8b
```

## 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](/guides/send-email-with-smtp#enable-smtp) 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](/guides/send-email-with-smtp#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](/platform/domains/introduction), 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](/api-reference/sending/send#send-multiple-emails-in-a-batch). See [Sending limits](/platform/emails/limitations#maximum-recipients). |
| `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](https://app.lettermint.co/team/billing), 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](#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](/guides/send-email-with-smtp#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](/guides/send-email-with-smtp#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](/platform/emails/limitations#email-size-limit).

## Attachments

Lettermint rejects messages with blocked attachment types with `550 5.7.1`. The reply text names the reason:

```text
550 5.7.1 Message contains disallowed file extension (exe)
550 5.7.1 Message contains unacceptable content type (application/x-msdownload)
```

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](/platform/emails/limitations#blocked-attachments) 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](/platform/projects-and-routes/sandbox-mode) accept up to 100 recipients per team per minute. Over that limit, Lettermint replies with a temporary failure:

```text
451 4.7.0 Sandbox accepts up to 100 recipients per team per minute.
```

Retry after a minute.