Errors & retries
HTTP status codes, the SMTP reply-code mapping, the auto-refund guarantee, and retry guidance for both channels.
Errors & retries
Both channels run the same send pipeline, so they reject for the same reasons. The HTTPS API reports those reasons as HTTP status codes; the SMTP relay maps them onto SMTP reply codes.
HTTPS status codes
Failures use the envelope { "ok": false, "error": "...", "code"?: "..." }.
| Status | When | Notes |
|---|---|---|
400 | Empty to, more than 100 recipients, an invalid address, missing body, or an unauthorized from | Validation; nothing was charged. |
401 | Missing bearer token, or the key was not found | Missing Authorization bearer token / Invalid API key. |
403 | The key exists but is disabled | This API key is disabled. Re-enable or rotate on the API Keys tab. |
402 | Not enough credits | code is INSUFFICIENT_CREDITS (pre-flight balance check) or INSUFFICIENT_FUNDS (lost a debit race). Top up, then retry. |
413 | Combined html + text body over 10 MB | Body must be under 10MB. |
429 | Over 120 calls/min for the key | Carries a Retry-After header in seconds. Back off and retry. |
502 | Terminal relay failure to the upstream mailbox | Credits charged for the request are refunded automatically. |
200 means sent; 202 means queued behind a per-address daily cap and will be delivered within 24 hours (see the daily cap).
SMTP reply-code mapping
The relay translates the same pipeline outcomes into SMTP reply codes so standard mail clients retry correctly:
| Pipeline outcome | SMTP reply | Client behavior |
|---|---|---|
| Rate limited | 421 | Transient; the client should retry later. |
| Insufficient credits | 451 | Local error; retry after topping up. |
| Bad or disabled key | 535 | Auth failure at AUTH, before DATA; do not retry without fixing the key. |
| Unauthorized sender, invalid body, oversize, or relay failure | 550 | Permanent; do not retry as-is. |
| Other transient errors | 451 | Retry later. |
On accept, DATA returns 250 OK: <messageId> (or 250 queued: <messageId> when the message was queued behind the daily cap).
Auto-refund on failure
If a send terminally fails after credits were debited (HTTPS 502, or the SMTP 550 relay-failure case), the charged credits are refunded automatically. You are not billed for mail that did not leave the system. Validation rejections (400, 401, 403, 413) never charge in the first place. A 402 means nothing was debited. A queued 202 is charged and not refunded, because it will be delivered.
Retry guidance
There is no idempotency key. Retrying a request that timed out or returned a 502 may send the message again if the original actually went through, so:
- Retry
429after theRetry-Afterwindow. Safe; the original was rejected before sending. - Retry
402after topping up. Safe; nothing was sent. - For
502or a network timeout, treat delivery as uncertain. If you must retry, expect a possible duplicate, and check the dashboard Logs tab to confirm whether the first attempt was logged assent.
No delivery feedback
messageId is returned only on the synchronous response. There is no delivery, open, or bounce webhook, and no public endpoint to look a message up by id. The only post-send record is the dashboard Logs tab, where each row is tagged with the channel it came in on (api or smtp) and a status of sent, queued, or failed.