Response Codes - MailBreeze

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

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.

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

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.

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.

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.

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.

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.

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.

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 or in your dashboard to see delivery, bounce, open, and click events.

​Authentication

​Sending

​Common problems

​Checking what happened to a message

Authentication

Sending

Common problems

Checking what happened to a message