Limits and errors
What refuses, when, and what the response tells you.
Limits refuse, they do not invoice
Every account has a hard monthly ceiling and the platform has one above it. Reaching either produces a refusal, never a surprise bill.
- At most 50 recipients per message, across to, cc and bcc together
- A recipient is one address on one message — that is how the quota counts
- Message size up to 40 MB including attachments
- Subject lines may not contain control characters, because that would allow header injection
Errors worth handling
Every error carries a stable code and a human sentence. The codes below are the ones your integration should branch on.
- 401 unauthorized — the key is missing, malformed or revoked
- 402 quotaExhausted — your monthly quota is used up, nothing was sent or billed
- 403 domainNotOwned — the from address is not a verified domain of this account
- 409 recipientSuppressed — a recipient bounced or complained before; the response lists them
- 422 validationFailed — the response names the offending field
- 503 dailyRecipientCap — the platform ceiling was reached; retry after the seconds given
Idempotency
Send the same Idempotency-Key twice and the second call returns the original message id instead of a second message. Use your own order or event identifier and retries become free of consequence.
Idempotency-Key: order-4711