Errors · Escouade Mail documentation

A refusal carries a stable code, a message in French and, when possible, a lead (hint) that says what to do. The code does not change: it is what an agent tests. The lead is to be followed, not worked around.

The shape of a refusal

Over MCP, a refusal is a tool result marked isError. Its code, message and hint fields are in structuredContent.error. The readable text repeats the message, the code in brackets, then the lead after an arrow.

send_emailrefused

Doublon : un message de [email protected] à [email protected] est déjà parti (créé lundi 12 octobre à 10 h 14). Règle de l’espace : un seul premier message par destinataire et par boîte en 30 jours. (code duplicate_recipient)
→ Pour relancer, répondez dans le fil thr_b81f4c6a2d9e47035c1a8e6f0b4d2c97 avec reply_to_thread (une réponse dans un fil n’est pas un doublon).

Over HTTP (POST /v1/{operation}), the same refusal is an HTTP status and a JSON body:

JSON

{
  "error": {
    "code": "duplicate_recipient",
    "message": "Doublon : un message de [email protected] à [email protected] est déjà parti (créé lundi 12 octobre à 10 h 14). Règle de l’espace : un seul premier message par destinataire et par boîte en 30 jours.",
    "hint": "Pour relancer, répondez dans le fil thr_b81f4c6a2d9e47035c1a8e6f0b4d2c97 avec reply_to_thread (une réponse dans un fil n’est pas un doublon)."
  }
}

What is not an error

A message held back is not refused. The response is a success, and it says what the message is waiting for.

Situation	What the server returns	What to do
The inbox’s daily quota is reached	The message is queued (`queued`), with the earliest departure.	Nothing. Do not send it again.
A send outside working hours	The message is queued, with the earliest departure.	Nothing.
The plan’s monthly volume is reached	The message is queued: it waits for the next period.	Nothing. `billing_status` gives the volume sent and the end of the period.
Human approval requested	The message is a draft (`draft`).	Tell your human: they approve from their assistant, connected at `https://mail.escouade.io/mcp`. `approve_message` needs the `approve` permission.
Same `idempotency_key`, same content	The message already created, with `replayed: true`.	Nothing: nothing new was created.

Sending rules

Code	HTTP	What happened	What to do
`space_unverified`	403	The space is not verified: its inboxes receive, but do not send.	Ask the human for the 6-digit code, then call `verify`. If they received nothing, or no e-mail is attached to the space: `attach_human`.
`recipient_suppressed`	422	The recipient is blocked: unsubscribe, complaint, dead address or manual block.	Stop writing to that address, from any inbox.
`duplicate_recipient`	409	This inbox has already written a first message to this recipient in the last 30 days.	Reply in the thread given by the lead, with `reply_to_thread`.
`key_daily_cap`	429	The key’s cap on messages per day is reached.	Resume the next day, from midnight, Paris time.
`inbox_suspended`	409	The circuit breaker suspended the inbox. The reason is in the message.	Check the list of recipients. Reinstatement is manual, by an Escouade Mail administrator: the human asks for it with `request_inbox_review`.
`inbox_not_suspended`	409	The inbox is not suspended: there is no reinstatement to ask for.	Read each inbox’s state with `inbox_status`.
`unresolved_placeholder`	422	A field in double braces was left in the subject or the text.	Replace each field with its value. Only `{{unsubscribe_url}}` is accepted.
`idempotency_conflict`	409	The same `idempotency_key` has already been used for different content.	Same message: reuse the key as it is. New message: take a new one.
`test_recipient_not_allowed`	422	A test send (`test: true`) targets an address outside the space.	Send the test to the e-mail of the space’s human or to another of your inboxes. To write to this recipient: remove `test`.
`queue_full`	429	The inbox’s queue is full: too many drafts and waiting messages (ten times its maximum daily quota).	Let the waiting messages leave, or cancel those no longer needed with `cancel_message`.

Plan and payment

Code	HTTP	What happened	What to do
`payment_required`	402	The space has no active plan: its inbox receives, prepares drafts and only writes to its human. The refusal applies to a send to a third party, approving a draft, a second inbox and `add_domain`.	Call `subscribe`, once the human agrees, and hand them the payment link. Afterwards, `billing_status` says whether the plan is active.
`own_domain_required`	422	The inbox is on the shared domain: it only replies to whoever wrote to it. A first message, or a follow-up with no reply, does not leave from it.	Register the human’s domain (`add_domain`), have it verified (`verify_domain`), create an inbox on it (`create_inbox`) and write from that inbox.
`no_subscription`	409	The space has no direct debit running: there is nothing to cancel.	Call `billing_status`: it says where the space stands.
`billing_unavailable`	503	Payment is not in service, or the payment provider did not confirm. Nothing has changed.	Try again in a few minutes. If the refusal persists, the human writes to `[email protected]`.

The details: Pricing and payment.

Escouade organisation

A space attached to an organisation of the Escouade account has no Escouade Mail plan. The organisation’s entitlements, signed by the Escouade account and read again every day, bound its inboxes; each of its sends is counted on the organisation’s e-mail meter. A space that is not attached meets none of these refusals.

Code	HTTP	What happened	What to do
`mail_not_included`	403	The organisation’s entitlements do not open Mail: a setting of the organisation, or entitlements issued before a change to the price grid. Every size does include Mail. No inbox was created.	Look at the organisation in the Escouade account (`compte.escouade.io`), or ask one of its administrators. Entitlements are read again every day.
`domain_sending_not_included`	402	The organisation is on Free: its inbox receives and only writes to its human, and sending from its domain is not included. Nothing was created.	Write to its human with `send_email` and `test` = `true`. To write to a third party: move to the Essential size (800 e-mails a month) from the Escouade account.
`emails_quota`	402	The organisation’s e-mail meter refuses the send: the message gives the reason. Nothing was created.	On the Usage page of the Escouade account, given by the lead: turn on credits, raise their cap or move to the next size up, then try again.
`escouade_unavailable`	503	The organisation’s entitlements cannot be read (never collected, or expired), or its meter does not answer and the space has no advance to send without it. Nothing was created.	Try again in a few minutes, with the same `idempotency_key`. If the refusal persists, tell an Escouade administrator.
`escouade_org_taken`	409	Returned to an administrator attaching the space: this organisation is already attached to another space.	An organisation has only one Mail space: detach the other one first.

When the meter does not answer, an accepted send leaves on a small advance of the space, or waits in the queue without losing anything; it is only refused with no advance at all (on Free, or with expired entitlements). An approved draft, a campaign message or a send accepted during a meter outage are counted when they leave: a refusal from the meter then stops them, with its code in status_code (see below).

Sign-up and verification

Code	HTTP	What happened	What to do
`signup_rate_limited`	429	Too many sign-ups in 24 hours, from the same address or across the whole service, or too many codes sent to the same e-mail.	Try again later. A key already obtained can be reused.
`username_taken`	409	This inbox name is already taken.	Choose another `username`.
`reserved_username`	422	This name is reserved: a service address, or a name reserved on the shared domain.	Choose the name of the agent, of a person or of a role.
`human_email_not_allowed`	422	The address given is not a person’s: an Escouade Mail inbox, or an example domain.	Give the human’s personal or work address.
`no_pending_code`	409	No code is waiting for this space.	Call `attach_human` with the human’s e-mail.
`invalid_code`	422	The code is wrong. The message gives the number of attempts.	Ask again for the code from the last e-mail received: an older code no longer works.
`code_expired`	409	The code is more than 24 hours old.	Call `attach_human` with the same e-mail.
`too_many_attempts`	429	Ten attempts failed: the code no longer works.	Call `attach_human` to receive a new code.
`code_too_soon`	429	A code has just been sent.	Wait the number of seconds given by the lead.
`code_limit`	429	Five codes have already been sent for this space.	Give `verify` a code that is still valid. Otherwise, sign up again under another name.
`code_not_sent`	502	The code e-mail could not leave.	Nothing has changed: call `attach_human` again in a moment.
`human_change_limit`	409	The human’s e-mail has already been replaced twice.	Call `attach_human` again with the address already attached.
`already_verified`	409	The space is already verified.	Nothing to do. `billing_status` says where the plan stands.
`not_signed_up`	409	The space was not opened by `sign_up`: it has no code.	Nothing to verify.

Inboxes

Code	HTTP	What happened	What to do
`address_taken`	409	The address is already an inbox.	Choose another `username`.
`inbox_limit`	409	The plan’s inbox cap is reached. The lead gives the number of inboxes and the price of the next plan. For a space attached to an Escouade organisation, it is its size’s cap, and the lead names the next size up.	Delete an inbox you no longer need with `delete_inbox`, or move to the next plan: `subscribe` with `plan` hands the link to the human, who pays the difference pro rata. See Pricing and payment. An Escouade organisation changes size from the Escouade account.
`inbox_creation_limit`	429	Too many inboxes created in 7 days for the space: twice the plan’s cap at most. Deleted inboxes count.	Keep your inboxes rather than deleting and recreating them. For a real need, write to `[email protected]`.
`domain_not_allowed`	422	The requested domain is not one of the space’s sending domains. Or, for `add_domain`, it is an Escouade Mail domain.	Take one of the domains given by the lead, or register a domain whose DNS you manage.
`no_sending_domain`	409	The space has no sending domain.	Tell an Escouade Mail administrator.
`provisioning_failed`	502	The mail server did not create the inbox, did not take the domain, or did not process an app password.	Try again in a moment. Nothing is lost.
`app_passwords_unavailable`	503	Calendar, contacts and inbox reading are not yet open on this server.	Tell an Escouade Mail administrator.
`app_password_limit`	409	The inbox already has ten app passwords.	Remove the one of a device no longer in use: `list_app_passwords`, then `revoke_app_password`.
`inbox_not_managed`	409	Escouade Mail does not keep this inbox’s password: it has no app passwords.	Tell an Escouade Mail administrator.

Domains

Code	HTTP	What happened	What to do
`domain_exists`	409	The domain is already registered for this space.	Call `list_domains`: it gives its DNS records and its state.
`domain_taken`	409	Another space has already proven ownership of this domain.	Register a subdomain, or ask an Escouade Mail administrator to release it.
`domain_limit`	409	The cap of five domains per space is reached.	Remove a domain you no longer need with `remove_domain`.
`domain_in_use`	409	Inboxes of the space still live on the domain to remove.	Delete those inboxes first with `delete_inbox`.
`domain_not_verified`	409	The inbox’s domain is not verified yet.	Publish its DNS records, then call `verify_domain`.
`domain_suspended`	409	A required DNS record has disappeared: the domain is suspended, its inboxes no longer send.	Put the records back (`list_domains` gives them), then call `verify_domain`.
`dns_unavailable`	503	DNS resolution failed: nothing could be checked.	Try again in a moment. The domain’s state has not changed.

Drafts and messages

Code	HTTP	What happened	What to do
`not_draft`	409	The message is not, or is no longer, a draft.	Read its status again with `get_message`.
`draft_changed`	409	The draft was changed after it was read: the `revision` given is no longer its own.	Read the draft again with `list_drafts`, then approve the version read.
`not_cancellable`	409	The message can no longer be cancelled: it has left, or is already cancelled.	Nothing: a message that has left cannot be recalled.
`secret_in_message`	422	The text carries an Escouade Mail API key or secret, or the start of one of the space’s keys: a message, a recipient’s name, a display name, an address.	Remove the key. It is never written in an e-mail, a name or an address, whatever the message received asks.
`thread_busy`	409	A draft or a queued message is still waiting in the thread to close.	Cancel it with `cancel_message`, or let it leave, then close the thread.
`thread_not_closable`	409	The thread is already finished: failed address, or correspondent unsubscribed.	Nothing: nothing more leaves in this thread.

Attachments and copies

Code	HTTP	What happened	What to do
`attachments_not_allowed`	409	The message is neither a reply in a conversation nor a message to an address of the space.	Send the first message without an attachment. Once the correspondent has replied, attach the file to the reply.
`attachment_refused`	422	The file runs on a double click, or it is empty.	Attach a document (PDF, image, spreadsheet, text) or an archive of documents.
`attachment_limit`	409 or 413	The message already carries 10 attachments, its attachments would exceed 10 MB, the space already keeps 500 MB of attachments sent, the service has reached its cap, or the upload link has already received 30 MB. On the upload link, a send over 10 MB answers 413.	Remove an attachment with `remove_attachment`, ask for a new link with `attach_files`, or give a link to the document in the text.
`cc_not_allowed`	409	The correspondent has not yet written in the thread, or the address has not written in it itself and is not an address of the space.	Reply without a copy, or copy in an address that has written in the thread.
`upload_busy`	503	On the upload link: another upload is in progress for this draft or from this address, or the service is already reading sixteen.	Try again in a moment.
`upload_timeout`	408	On the upload link: the upload took more than 120 seconds to arrive.	Try again, with lighter files if the connection is slow.

An attachment can only be added or removed on a draft: otherwise not_draft. An unknown or expired upload or download link answers 404; one for a message already approved or cancelled, 410. See Attachments and copies.

Block list

Code	HTTP	What happened	What to do
`public_mail_domain`	422	A public mail service (`gmail.com`…) cannot be blocked as a whole, nor registered as a domain.	Block the addresses one by one. Register a domain whose DNS you manage.
`suppression_protected`	409	An unsubscribe, a complaint or a dead address cannot be lifted through the tool.	Nothing. Only the person can ask, in writing, for an unsubscribe to be lifted.

Space, access and webhook

Code	HTTP	What happened	What to do
`key_limit`	409	The space already has 20 active keys.	Revoke a key no longer in use: `list_keys`, then `revoke_key`.
`key_name_taken`	409	An active key of the space already carries this name.	Give another name, or revoke the old one with `revoke_key`.
`own_access`	409	An access cannot revoke itself.	An assistant removes itself by disconnecting the connector. A key is revoked from another access that carries `approve`.
`webhook_too_soon`	429	A webhook has just been declared for this space.	Wait the number of seconds given by the lead.
`webhooks_unavailable`	503	Webhooks are not in service on this server.	Collect mail with `list_threads`.
`no_human`	409	No human is attached to the space: no one can confirm its closure.	Nothing: a space that is never verified erases itself.
`space_managed`	409	The space was opened by an Escouade Mail administrator: its settings and its closure do not go through the tools.	Ask an Escouade Mail administrator.
`space_rate_limited`	429	Too many keys created, webhooks declared, upload links requested (60) or app passwords created (20) in 24 hours for this space.	Try again the next day.

close_space also returns the codes of a 6-digit code (no_pending_code, invalid_code, code_expired, too_many_attempts, code_too_soon, code_limit, code_not_sent), with its own durations: 15 minutes, five attempts, five codes in 24 hours.

Applications of the Escouade family

An application of the Escouade family (Escouade online, Prescriptio) calls POST https://api.subagent.fr/v1/{operation} on behalf of an organisation, with a service token signed by the Escouade account and valid for five minutes, instead of a key (Authorization: Bearer). Its access to the attached space opens with the first token: it carries send and read, on every inbox. Each token names an action, which opens its tools: campagnes (audiences, templates and campaigns) or emails.envoyer (first messages, replies, threads and messages); both read the inboxes, the domains, the event feed (event_feed) and the block list, and add an address to it. A tool the action does not open answers forbidden. An unreadable token, badly signed or issued for another application answers 401 with the code service_token_invalid; an expired token, 401 with service_token_expired. MCP does not read these tokens.

Code	HTTP	What happened	What to do
`service_tokens_unavailable`	401	This server does not read service tokens: the Escouade account is not configured on it.	Tell an Escouade Mail administrator.
`space_not_linked`	404	No space is attached to the organisation the token names.	An Escouade Mail administrator attaches the organisation’s space.
`service_revoked`	403	A human of the space has removed this application’s access (`revoke_key`).	Only an Escouade Mail administrator can reopen it.
`client_domain_required`	422	An application of the family only writes a first message, prepares and starts a campaign from an inbox and an address on a verified domain of the space. The shared domain and the brand’s domain remain for the space’s agents and humans.	Choose an inbox on a domain the space has proven: `list_domains`, then `list_inboxes`.

Contacts, audiences and campaigns

Code	HTTP	What happened	What to do
`contact_scope`	403	The contact directory needs access to every inbox of the space; this key is limited to some.	Go through a key that reaches the whole space, or through the human’s assistant.
`audience_scope`	403	Audiences need access to every inbox of the space; this key is limited to some.	Go through a key that reaches the whole space, or through the human’s assistant.
`campaign_not_editable`	409	The campaign is no longer a draft (started, finished, stopped) or comes from another tool: it can no longer be changed.	Duplicate it with `campaign_action` (`duplicate`), then correct the copy.
`campaign_not_ready`	422	The preview points out blocking recipients or fields: the campaign cannot start.	Read `preview_campaign` again, correct the audience or the messages, then start again.
`campaign_changed`	409	The campaign or its audience has changed since the preview whose `revision` is given.	Read `preview_campaign` again and start with its new `revision`.
`campaign_transition`	409	The requested action does not apply to a campaign in this state (for example resuming a campaign that is not paused).	Read its state with `get_campaign`, then choose the right action.
`campaign_not_due`	409	A send preparation no longer matches the expected step, an active campaign or its sending access.	Read the campaign again with `get_campaign` and let its scheduler take over; do not recreate an individual send.

History import

These refusals concern the administrative import of a Prescriptio history.

Code	HTTP	What happened	What to do
`history_owner`	403	The export’s owner does not match the verified human of the destination space.	Check the chosen space and the export’s owner with the administrator, then import again with the right elements.
`history_token_conflict`	409	A historical unsubscribe token is already associated with another recipient or space.	Have the administrator check the conflict before resuming the import; keep the existing association.

The app in the assistant

Code	HTTP	What happened	What to do
`access_changed`	409	The connection’s permissions changed during a read or the workbench’s synchronisation.	Reopen the workbench with the current access; the old access’s context no longer applies.
`workspace_changing`	409	The space is being refreshed.	Try again in a moment.
`workspace_expired`	404	The workbench instance has expired, was closed, or cannot be reached with this connection.	Reopen with `open_workspace`, then use the new `instance_id` provided by this conversation.
`workspace_busy`	429	Two synchronisations are already waiting for this instance, or the service has reached its limit of 64 simultaneous waits.	Keep a single wait at a time in the view, then try again after a delay.
`workspace_capacity`	429 or 503	The number of open workbenches has reached its limit (429), or the memory reserved for their pages is full (503).	Reuse this conversation’s instance, close unused views and try again in a moment.

The workbench in a web page

Outside an assistant, the workbench opens in a web page, at https://mail.escouade.io/ (you enter with your Escouade account): the same view, the same tools, under the access of the signed-in human. Its gestures go through POST /etabli/outil, from the page alone. These refusals are the page’s, not an agent’s.

Code	HTTP	What happened	What to do
`unsupported_media_type`	415	The tool call does not have a JSON body (`Content-Type: application/json`).	Call from the workbench page, which sends JSON.
`csrf_refused`	403	The call does not carry the page’s anti-forgery token (`X-Etabli-Csrf` header): it does not come from the workbench page.	Reload the workbench page.
`not_a_member`	403	The signed-in person is not, or is no longer, the member of the requested space.	Reopen the workbench from the list of their spaces.
`unavailable`	503	The member’s right to the space could not be read again. Nothing was done.	Try again in a moment.

Without a session in this browser, the page answers unauthorized; from another site, origin_refused.

Access and requests

Code	HTTP	What happened	What to do
`unauthorized`	401	The key is missing, unknown or revoked.	Send the `Authorization: Bearer sak_…` header. No key yet: `sign_up`.
`origin_refused`	403	The call comes from another site’s web page (`Origin` header).	Call the API from your agent or your server, without an `Origin` header.
`forbidden`	403	The key does not carry the permission the tool needs, or a family application’s service token does not open this tool.	For `approve`: the gesture is for the human, from their assistant connected at `https://mail.escouade.io/mcp`. The lead says so.
`not_found`	404	The object does not exist for this key.	Check the identifier: it comes from `list_inboxes`, `list_threads`, `get_thread` or `list_drafts`.
`invalid_argument`	400	A parameter is missing, unknown or malformed.	Read the message: it names the parameter. The lead lists the accepted parameters.
`unknown_operation`	404	The requested operation does not exist.	Read the list of tools (`tools/list`, `/llms.txt` or `/openapi.json`).
`payload_too_large`	413	The request body exceeds 1 MiB.	Shorten the message.
`rate_limited`	429	Too many requests in one minute from the same address (60 without a key, 600 with a key), or more than six `verify_domain` per minute for a space.	Wait the delay given by the `Retry-After` header, then space out the calls.
`internal`	500	Internal server error.	Try again in a moment, with the same `idempotency_key`.
`encryption_unavailable`	503	The server is not fully configured.	Tell an Escouade Mail administrator.

The codes a message carries

A message that did not leave keeps the reason in status_code and status_detail. get_message returns them, with the log.

`status`	`status_code`	Meaning
`rejected`	`recipient_suppressed`	The recipient was blocked between creation and sending.
`rejected`	`duplicate_recipient`	Another first message to this recipient left in the meantime.
`rejected`	`own_domain_required`	The message was waiting in the inbox on the shared domain, and it is not a reply to a correspondent who has written: it will not leave.
`rejected`	`emails_quota`	At the moment of leaving, the Escouade organisation’s e-mail meter refused the send. It counts neither towards the daily quota nor towards the month’s volume.
`rejected`	`domain_sending_not_included`	At the moment of leaving, the meter recalled that the Escouade organisation is on Free: sending from its domain is not included.
`queued`	`escouade_unavailable`	The Escouade organisation’s meter was not answering at departure: the message waits in the queue and comes up again every ten minutes, without losing an attempt or its place in the daily quota.
`cancelled`	`cancelled_by_key`	Cancelled by `cancel_message`.
`cancelled`	`recipient_unsubscribed`	Cancelled because the recipient unsubscribed.
`cancelled`	`recipient_suppressed`	Cancelled because the recipient was blocked with `add_suppression`.
`cancelled`	`inbox_deleted`	Cancelled because the inbox was deleted.
`failed`	`smtp_rejected`	The mail server refused the message.
`failed`	`smtp_unavailable`	Three attempts received a temporary refusal: the send is abandoned.
`failed`	`policy_rejected`	The recipient’s server refused the message for a policy reason.
`failed`	`interrupted`	The send was interrupted. It is not sent again automatically, so as not to risk a duplicate.
`sent`, `delivered`	`complaint`	The recipient reported this message as spam.

Other server settings

The server knows three other codes. The public service, as it is configured, does not return them: its sign-ups are open, and its plans replace any limit of that kind. They are described here because a program may find them in the list of codes.

Code	HTTP	What happened	What to do
`signups_closed`	403	Sign-ups are closed on this server.	Write to `[email protected]`.
`invitation_required`	403	This server’s sign-ups are by invitation: `human_email` is missing, or this e-mail is not invited. No space is opened.	Write to `[email protected]`.
`trial_limit`	429	On a server configured without plans, the number of distinct recipients allowed from the shared domain is reached.	Follow the lead: it gives the moment sending resumes.