Email Center API errors: email_account_required, all_recipients_suppressed and other reasons

The short answer: the HTTP code tells you the kind of problem and the details.reason field tells you the exact reason. In Email Center the most common are email_account_required (the service is not active), domain_not_verified (the sender is not on a verified domain) and all_recipients_suppressed (every recipient is suppressed). Always use code and reason in your program, never the message text.

403: the account or the key

Code and reason	What it means	What to do
forbidden + email_account_required	The account does not have Email Center active	Turn it on on the Transactional e-mail page in My MozOut
insufficient_scope	The key lacks the permission	Create a key with email_center:write (or email_center:read to look things up)

422: the e-mail data

Reason	What to fix
domain_not_verified	from must be on a verified domain. See sender domain not verified
from_required / from_invalid	The sender is missing or the address is not valid
invalid_recipient / too_many_recipients	Invalid addresses or more than 50 recipients
all_recipients_suppressed	All of them are on the suppression list: nothing is sent or charged. See the suppression list
subject_required / subject_too_long	No subject, or longer than 998 characters
content_required	Send html, text or a template_id
template_not_found / invalid_variables	The template is not on this account, or variables is not an object
attachment_blocked / attachments_too_large	A forbidden file or attachments that are too big. See attachments
invalid_send_at / send_at_in_past / send_at_too_far	The schedule date. See scheduling
insufficient_credits / daily_limit_reached	No credits, or the daily limit reached. See credits and the daily limit

409: the current state does not allow it

Reason	What it means
domain_exists	The domain is already on your list
domain_in_use	The domain is already verified on another account. Get in touch with us
domain_limit / template_limit	You reached the maximum number of domains or templates
template_name_exists	There is already a template with that name
not_cancellable	Only scheduled e-mails that have not gone out can be cancelled
idempotency_conflict	The same Idempotency-Key with a different body, or with the first request still running

Retry or fix

Only 429, 500, 502 and 503 are worth retrying, after a wait. The others come back the same until you fix the request. Always retry with the same Idempotency-Key, so the e-mail never goes out twice.

Keep the correlation_id of every error. If you need help, send it to support with the time of the request. Never send the key: support does not need it.

An error you cannot solve? Open a support ticket with the correlation_id.

Open a support ticket

Categories

Categories