Errors

Errors are JSON with a stable code, a plain-language message and a docs link to the section below:

{ "error": "monthly_cap_reached", "message": "You've reached your plan's monthly send cap...", "docs": "https://app.emitemail.com/docs/errors#monthly_cap_reached" }

Branch on error, never on the message text. Do not retry 4xx errors except 409.

missing_api_key#

HTTP 401

The request had no Authorization: Bearer header.

invalid_idempotency_key#

HTTP 400

The Idempotency-Key is not 1 to 128 characters of letters, numbers and . _ : -.

invalid_request#

HTTP 400

A field is missing or malformed, or an unknown field was sent. The message says which. Fix the request.

invalid_api_key#

HTTP 401

The key is missing, wrong or revoked. Check the Authorization: Bearer header and that the key is still active under API keys.

sender_domain_not_found#

HTTP 403

The from domain is not on your account. Add it under Domains.

sender_domain_not_verified#

HTTP 403

The domain's DNS records are not verified yet. Publish them and click Verify. See Domains.

api_key_domain_mismatch#

HTTP 403

This key is limited to a different domain. Use a key for this domain or create one.

account_suspended#

HTTP 403

Sending is paused on the account or on the brand you are sending from. There are three causes, and the message says which. emitemail paused it automatically because many emails bounced or were reported as spam (we email the account owner). You paused the brand yourself: resume it under Brands in the dashboard. Or support paused it after an abuse report. For the first and third, write to support to restore it. Other brands on the account are not affected. See Limits and the cap.

idempotency_in_progress#

HTTP 409

A request with the same Idempotency-Key is still being processed. Retry in a moment. See Retries.

all_recipients_suppressed#

HTTP 422

Every recipient bounced or reported spam before. Nothing was sent. See Bounces and suppressions.

idempotency_key_reuse#

HTTP 422

That Idempotency-Key was already used with a different message. Use a new key for a new message.

monthly_cap_reached#

HTTP 429

Your plan's monthly cap is used up. Nothing is sent and nothing is billed. Sending resumes on the first of the month (UTC), or straight away if you upgrade. Do not retry until then. See Limits and the cap.

daily_limit_reached#

HTTP 429

The daily limit was reached: 100 emails a day on the Free plan, or 50 a day while an account is new (until it has sent 100 emails). It resets at midnight UTC. Paid plans have no daily limit once the account is past that.

brand_budget_reached#

HTTP 429

The monthly or daily budget you set on this brand is used up. Nothing is sent and nothing is billed. The message says which one. Sending resumes when the period resets, or straight away if you raise or clear the budget under Brands. Do not retry until then. See Brands.

rate_limited#

HTTP 429

Too many emails in a minute: 10 a minute on the Free plan and on new accounts. The response has retry_after (seconds) and a Retry-After header, so wait that long and retry. If one request has more recipients than the per-minute limit, it can never succeed: send in smaller batches. Over SMTP this is a temporary 451 error, which SMTP clients retry on their own.