> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mailbreeze.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Response Codes

> What each SMTP reply from MailBreeze means and how your client should react

MailBreeze follows standard SMTP conventions: a `4xx` reply is temporary and your client should retry, a `5xx` reply is permanent and retrying will not help.

## Authentication

| Reply                                     | Meaning                                       | What to do                            |
| ----------------------------------------- | --------------------------------------------- | ------------------------------------- |
| `235 Authentication successful`           | The key is valid                              | —                                     |
| `535 Invalid credentials`                 | The password is not a valid API key format    | Check for a truncated or wrapped key  |
| `535 Invalid API key`                     | The key does not exist or was revoked         | Issue a new key in the dashboard      |
| `535 API key has expired`                 | The key passed its expiry date                | Issue a new key                       |
| `535 IP not in API key whitelist`         | The key restricts source IPs                  | See below                             |
| `535 Sending disabled for this domain`    | The domain is suspended or unverified         | Check the domain in your dashboard    |
| `538 Must issue a STARTTLS command first` | Credentials offered on a plaintext connection | Enable TLS or STARTTLS in your client |

<Warning>
  **IP whitelists and SMTP.** An API key's IP whitelist is checked against the server making the SMTP connection, which is often not the server that calls the REST API. Applications hosted on platforms with rotating egress addresses — Shopify, Vercel, most PaaS providers — cannot be pinned to a fixed IP. Use a key without an IP whitelist for SMTP.
</Warning>

## Sending

| Reply                                                | Meaning                                        | What to do                           |
| ---------------------------------------------------- | ---------------------------------------------- | ------------------------------------ |
| `250 Accepted <id>`                                  | Queued for delivery                            | Record the ID for later lookup       |
| `530 Authentication Required`                        | `MAIL FROM` issued before authenticating       | Configure credentials in your client |
| `550 From-address domain must match verified domain` | The From address is on another domain          | Send from your verified domain       |
| `550 At least one To or Cc recipient is required`    | Bcc-only message                               | Add a To or Cc recipient             |
| `550 Recipient is suppressed`                        | The address bounced or unsubscribed previously | Remove it from your list             |
| `550 All recipients are suppressed`                  | Every recipient is suppressed                  | —                                    |
| `550 Message has no subject`                         | Missing subject                                | —                                    |
| `550 Message exceeds the maximum size`               | Over 25 MB                                     | Reduce attachment size               |
| `452 Too many recipients`                            | Over 50 recipients                             | Split into several messages          |
| `452 Insufficient credits`                           | The account is out of credits                  | Top up; your client will retry       |
| `451 Temporary failure, retry later`                 | A transient problem on our side                | Let your client retry                |
| `421 Too many concurrent connections`                | Over 10 open connections from one IP           | Reduce your connection pool          |
| `421 Too many failed authentication attempts`        | Locked out for 15 minutes                      | Correct the credentials and wait     |

## Common problems

<AccordionGroup>
  <Accordion title="Mail is queuing on my server and never sends">
    Most often a revoked or rotated API key. A mail server treats a `535` as a deferral and keeps retrying quietly, so nothing appears to fail. Check your mail log for `535` and confirm the key is still active in your dashboard.
  </Accordion>

  <Accordion title="Authentication works from my laptop but not from my server">
    Almost always an IP whitelist on the key. Your laptop and your server connect from different addresses. Remove the whitelist or use a key without one.
  </Accordion>

  <Accordion title="Replies start a new conversation instead of threading">
    Your client is not sending `In-Reply-To` and `References`. MailBreeze preserves both when present but does not invent them.
  </Accordion>

  <Accordion title="A Bcc recipient can see the other recipients">
    This should not happen. Blind recipients never appear in any header MailBreeze generates. If you see otherwise, check whether your client is placing those addresses in the `To` or `Cc` header itself before sending.
  </Accordion>

  <Accordion title="The same message arrived twice">
    Your client generated a different `Message-ID` on retry, so the two attempts could not be matched. Configure it to reuse the `Message-ID` when retrying.
  </Accordion>

  <Accordion title="Connections time out on port 587">
    Some hosting providers and residential ISPs block outbound 587. Try port 2525, which is offered for exactly this reason.
  </Accordion>
</AccordionGroup>

## Checking what happened to a message

The ID returned in the `250` reply is the same one used across the platform. Look it up through the [get email endpoint](/api-reference/emails/get) or in your dashboard to see delivery, bounce, open, and click events.