Errors and limits

What an error looks like, what each code means, and the limits your plan sets.

Errors

A failed request has a non-2xx status and a JSON body. Branch on error.code, which is stable. The message is for people and its wording can change.

Example

curl -i https://app.mailbench.dev/v1/inboxes/box_missing \
  -H "Authorization: Bearer $API_KEY"

HTTP/2 404
{"success":false,"error":{"code":"not_found","message":"Inbox not found"}}

Error codes

HTTP	Code	What it means
400	`invalid_body, invalid_query, invalid_name, invalid_url, invalid_cursor, invalid_index, …`	The request was rejected. The message says which value and why. Fix the request; retrying will not help.
400	`not_configured`	The feature is not set up on this server (for example, spam checking).
401	`unauthorized`	The API key is missing, malformed or revoked.
402	`limit_reached`	Doing this would go over your plan, for example a second webhook on the Free plan.
402	`quota_reached`	The workspace has used its emails for the month. Sending over SMTP answers 552 for the same reason.
403	`forbidden`	The key is read-only, or your role is not enough.
403	`session_required`	This needs a signed-in dashboard session. API keys cannot do it.
404	`not_found`	No such object in this workspace. Objects in other workspaces look the same.
404	`wait_timeout`	The wait ended before a matching email arrived. Not an error in your request; try again or check your app sent it.
409	`conflict`	It already exists, for example an inbox with the same name.
429	`rate_limited`	Too many requests. Wait the number of seconds in Retry-After.
500	`internal_error`	Something went wrong on our side. Retry; if it persists, contact support.
502	`upstream_error, …`	A service we depend on failed (for example the spam checker). Retry later.

Retry 429, 500 and 502 with a short, growing delay. Do not retry other 4xxerrors without changing something.

Rate limits

API requests are limited per workspace, by plan. Short bursts up to two seconds' worth of requests are allowed. Over the limit you get 429 with a Retry-After header in seconds.

Plan	Requests per second
Free	10
Pro	30
Team	100

A long-running wait counts as one request however long it stays open. Sending mail over SMTP has its own limit: each inbox accepts about ten messages a second, in bursts of up to fifty. Past that the server answers 450, which a normal mailer retries on its own.

Plan limits

Plan	Emails per month	Retention	Members	Webhooks
Free	2,500	7 days	5	1
Pro	50,000	30 days	Unlimited	10
Team	250,000	90 days	Unlimited	Unlimited

Emails per month. Every message an inbox accepts counts, whether it arrives over SMTP or the API. The month is the calendar month in UTC. At the limit, SMTP answers 552 and POST /v1/inboxes/{id}/send answers 402 quota_reached. Nothing is lost that was already stored.
Retention. Messages older than your plan's retention are deleted, along with their attachments.
Going over after a downgrade. Existing members and webhooks are kept, but you cannot add more until you are back under the limit.

Message size

The SMTP server accepts messages up to 25 MB and rejects larger ones. Connect on port 587 (STARTTLS), 465 (TLS) or 2525.