Errors

Every refusal code Mail returns, the HTTP status it has on the API, and what to do about it.

reference~4 minVerified v0.216.0

Every error is JSON with a stable code and a message that says what to do.

json

{ "error": { "code": "read_only", "message": "This connection is read only, so mail_send was not run…" } }

Read the code, not the message. Over MCP the same code comes back as a tool error. Over the HTTP API it also has the HTTP status below. A code the API does not list arrives with status 502 and its own code.

A send that came back failed or rejected is an error too, never a 200, and that includes a retry with the same idempotency_key of a send that failed earlier.

Key and route errors

These come from the API itself, before a tool runs.

Status	Code	Meaning
401	`unauthorized`	No key, a revoked key, or a key Mail no longer knows. Send `Authorization: Bearer sam_…`. A Super Artifacts key does not work here.
404	`not_found`	No such route, or no such mailbox or thread is open to this key.
405	`method_not_allowed`	The route exists but not for that method. The `Allow` header lists the right ones.

Bad requests, 400

Code	Meaning
`invalid_arguments`	The arguments do not match the tool's schema. The message names the problem, and the tool did not run.
`invalid_json`	The request body is not valid JSON.
`invalid_body`	The request body must be a JSON object.
`invalid_request`	A name or query is not valid, or the message has no recipients.
`unsafe_webhook_url`	The webhook address is refused: it must be https on port 443 with a public host name.

Not allowed, 403

Code	Meaning
`read_only`	A read only connection called a tool that sends mail or changes something. A person can change the agent's access on Agents in the Mail dashboard.
`forbidden`	The action needs the Owner role in the workspace.
`role_required`	Connecting Mail needs the Owner or Editor role. A Viewer cannot.
`plan_required`	The plan does not include this. Shared mailboxes are on Team.
`mode_not_allowed`	The plan does not allow the way the mailbox is set to send.
`domain_allowance_reached`	The domain is beyond the custom domains the plan includes.
`not_allowed_to_send`	The workspace was deleted, or the agent that wrote the message no longer has a live Mail key, or the person who approved it is no longer a member. Nothing was sent.

Not found, 404

Code	Meaning
`no_mailbox`	The agent has no mailbox of its own yet. Call `mail_mailboxes` to see why.
`domain_not_found`	The workspace has no such domain. An owner adds one under Settings, then Domains.
`artifact_not_in_workspace`	The `artifact` link on `mail_reply` is not published in this workspace, or it was deleted.

Conflicts, 409

Code	Meaning
`address_taken`	That address is already in use. Pick another.
`address_reserved`	That name is reserved and cannot be an address.
`domain_not_verified`	The domain's DNS records are not verified, so no address can open on it.
`mailbox_closed`	The mailbox is closed because its agent was disconnected or its last Mail key was revoked.
`mailbox_paused`	Sending from the mailbox is paused. The message says why.
`allowance_reached`	The workspace has used every mailbox its plan allows.

Too large, 413

Code	Meaning
`payload_too_large`	The request body is over 512 KB.
`body_too_large`	A body is over the size cap.
`attachment_cap`	The attachments are larger than the plan allows.

Rejected, 422

Code	Meaning
`send_rejected`	The send was rejected and nothing went out.

Limits, 429

Code	Meaning
`rate_limited`	A rate limit was reached. Wait and try again.
`daily_cap`	The workspace has sent as many messages as its plan allows today.
`monthly_cap`	The workspace has used every send its plan allows this month.

Mail gives no reset time, so there is no Retry-After header. See Limits for the numbers.

Server errors

Status	Code	Meaning
500	`unknown_tool`	A server bug. The routes never name an unknown tool.
502	`mail_unavailable`	Mail could not answer. Try again in a moment.
502	`ingest_unavailable`	Mail's receiving side is not available. Try again in a moment.
502	`artifact_unavailable`	The artifact link could not be checked right now. Nothing was sent.
502	`send_failed`	The mail provider did not accept the message. It was not sent.
502	`internal`	An unexpected failure. Try again in a moment.