> Pour un agent : la carte de la documentation d'Escouade Mail est sur https://escouade.io/mail/docs/llms.txt ; chaque page existe en Markdown, à la même adresse suffixée `.md`.

# Boîtes

> Une boîte est une adresse e-mail pilotée par un agent. Elle reçoit dès sa création. Ses envois montent par paliers, semaine après semaine.

## Ce qu'est une boîte

- **Une adresse** `nom@domaine` et un nom affiché dans « De : ». Le mot de passe est géré par Escouade Mail et n'est jamais rendu : la boîte se pilote par les outils, pas par SMTP. Un téléphone affiche son agenda et ses contacts, et Escouade la lit, chacun avec son mot de passe d'application : voir [Agenda et contacts](https://escouade.io/mail/docs/agenda-et-contacts.md).
- **Toute boîte reçoit.** Un e-mail reçu ouvre un fil, ou s'ajoute au fil de son correspondant. Voir [Fils](https://escouade.io/mail/docs/fils.md).
- **Ses envois montent par paliers** : 5 e-mails par jour la première semaine, puis 10, 15 et 20. Le calendrier démarre à la création de la boîte. Voir [Règles d'envoi](https://escouade.io/mail/docs/regles-envoi.md#montee-progressive).
- **Un état** : `active`, `suspended` (le coupe-circuit l'a arrêtée, rien ne part) ou `deleted`.
- **Un plafond par espace** : une boîte avant le paiement, puis 2, 5 ou 15 selon le forfait. Au-delà, `create_inbox` est refusé. Tous les nombres : [Limites et quotas](https://escouade.io/mail/docs/limites.md).

## La première boîte

`sign_up` ouvre une boîte sur le domaine commun, `subagentmail.fr`. Ce qu'elle fait dépend de deux choses : le code à 6 chiffres, puis le forfait.

| Moment | Ce que fait la boîte |
|---|---|
| Avant le code à 6 chiffres | Elle reçoit et n'envoie pas : tout envoi est refusé avec le code `space_unverified`. |
| Après le code, avant le paiement | Elle reçoit, prépare des brouillons et n'écrit qu'à son humain : `send_email` avec `test`. Tout autre envoi est refusé avec le code `payment_required`. |
| Une fois le forfait payé | Elle répond à qui lui a écrit. Un premier message, ou une relance sans réponse, est refusé avec le code `own_domain_required`. |

- **Pour écrire le premier à quelqu'un**, il faut une boîte sur le domaine du client : voir [Domaines](https://escouade.io/mail/docs/domaines.md).
- **Un envoi de test passe toujours** : il ne part que vers l'e-mail de l'humain de l'espace, ou vers une autre boîte de l'espace.
- La règle vaut pour toute boîte du domaine commun, pas seulement la première.

Les forfaits et le paiement : [Prix et paiement](https://escouade.io/offre).

## `inbox_status`

Le point de départ. Il dit sur quel espace travaille la clé, s'il est vérifié, où en est son forfait, ses permissions, le créneau d'envoi, et l'état de chaque boîte. À appeler avant d'envoyer, et quand un envoi tarde. Toute clé peut l'appeler.

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `inbox_id` | identifiant `inb_…` | non | Une boîte précise. Absent : toutes les boîtes de la clé. |

```text
Espace Atelier Exemple (marque Subagent), 13 octobre 2026. Clé « Claude (marie@exemple.fr) » : send, read, approve, manage_inboxes.
Forfait à 19 € par mois, payé jusqu’à jeudi 12 novembre à 14 h 32 (détail : billing_status).
Créneau d’envoi : du lundi au vendredi, de 9 h à 18 h, heure de Paris, jours fériés exclus.
Boîte agent@exemple.fr (inb_3f9c2a7e5b1d4c8e9a0f6b2d7c4e1a95) — active
  Quota du jour : 9/15 envoyés, 6 restants (semaine 3 du réchauffage, palier de 15 par jour).
  En file : 3 ; brouillons à valider : 3. Prochain départ au plus tôt : mardi 13 octobre à 14 h 31.
```

L'objet structuré porte :

| Champ | Contenu |
|---|---|
| `tenant` | L'espace : `id`, `name`, `brand`, et `domains`, les domaines où il peut créer une boîte. |
| `verified` | `true` : l'espace est vérifié. `false` : ses boîtes reçoivent seulement. |
| `trial` | `null` dans le service public. Le champ ne sert qu'à un serveur réglé sans forfaits. |
| `key` | La clé : `name`, `permissions`, `daily_cap`. |
| `send_window` | Le créneau d'envoi, en clair. |
| `require_approval` | `true` : tout envoi de l'espace attend une validation humaine. |
| `now` | L'instant de cet état, en ISO 8601, à l'heure de Paris. |
| `inboxes` | Les boîtes, chacune avec les champs ci-dessous. |

Le texte dit en une ligne où en est le forfait. Le détail, avec la période, le volume parti et les factures, est rendu par `billing_status` : voir [Prix et paiement](https://escouade.io/offre).

Dans un assistant qui affiche les vues MCP Apps, `inbox_status` s'accompagne d'une vue : l'état des boîtes, dessiné à partir du même objet. Elle ne dit rien que le texte ne dise. `list_inboxes` a la sienne : une ligne par boîte. Voir [Vues](https://escouade.io/mail/docs/vues.md).

## Les champs d'une boîte

| Champ | Contenu |
|---|---|
| `id` | L'identifiant de la boîte, `inb_…`. |
| `address` | L'adresse e-mail. |
| `display_name` | Le nom affiché des envois. |
| `status` | `active`, `suspended` ou `deleted`. |
| `status_reason` | La raison d'une suspension, sinon `null`. |
| `created_at` | La date de création de la boîte, en ISO 8601. |
| `warmup` | La montée progressive : `week` (semaine en cours), `tier_limit` (palier), `steps` (les paliers), `complete` (dernier palier atteint), `start_date`. |
| `quota` | `daily_quota` (quota du jour), `daily_max` (quota maximal), `sent_today`, `remaining_today`. |
| `queued` | Le nombre de messages en file. |
| `drafts` | Le nombre de brouillons à valider. |
| `next_send_at` | Le prochain départ au plus tôt, ou `null` si rien n'est en file. |
| `send_window` | Le créneau d'envoi, en clair. |

## `activity_report`

Le point du jour et le bilan. Il dit en un appel ce qui attend une décision humaine, et ce que les boîtes ont envoyé et reçu : aujourd'hui, ou sur les sept derniers jours. À appeler quand l'humain demande où en est son espace, ou un bilan. Permission : `read` ou `approve`. L'espace n'a pas à être vérifié.

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `period` | texte | non | `today` : le jour en cours, à l'heure de Paris. `week` : les sept derniers jours, aujourd'hui compris. `today` par défaut. |
| `inbox_id` | identifiant `inb_…` | non | Une seule boîte. Absent : toutes les boîtes de la clé. |

```text
Point du jour, 13 octobre 2026, espace Atelier Exemple.
À décider : 3 brouillon(s) à valider (list_drafts) ; 1 message(s) reçu(s) sans réponse (list_threads avec unanswered = true).
Aujourd’hui : 9 envoi(s) sur 15 possible(s), 3 en file, 1 réponse(s) reçue(s), 0 rebond(s), 0 désinscription(s), 0 plainte(s).
```

L'objet structuré porte :

| Champ | Contenu |
|---|---|
| `period` | `kind` (`today` ou `week`), `from` et `to` : les jours de la période, à l'heure de Paris, compris. |
| `pending` | Ce qui attend une décision : `drafts` (le compte, et les cinq brouillons les plus récents), `replies` (le compte, et les cinq fils les plus récents dont le dernier message est un e-mail reçu sans réponse), `domains` (les domaines non vérifiés), `suspended_inboxes`. |
| `totals` | Sur la période : `sent` (les envois comptés au quota), `quota` (la somme des quotas du jour), `queued` (en file à l'instant), `replies`, `bounces`, `unsubscribes`, `complaints`. |
| `by_day` | Un objet par jour de la période, dans l'ordre : `date`, `sent`, `quota`, `replies`, `bounces`, `unsubscribes`, `complaints`. |
| `billing` | Où en est le paiement de l'espace, ou `null`. |
| `inboxes` | Les boîtes, avec [les champs d'une boîte](#champs). |

- **Rien n'est estimé.** Les envois sont ceux que compte le quota du jour. Les réponses, les rebonds, les désinscriptions et les plaintes viennent du journal.
- **`replies` et `domains` suivent les permissions** : `replies` vaut `null` sans `read`, `domains` vaut `null` sans `read` ni `manage_inboxes`.
- Dans un assistant qui affiche les vues MCP Apps, `activity_report` s'accompagne d'une vue : le point du jour. Voir [Vues](https://escouade.io/mail/docs/vues.md).

## `list_inboxes`

Liste les boîtes que la clé peut utiliser, avec leur quota du jour et leur palier. Toute clé peut l'appeler.

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `cursor` | texte | non | Le curseur de la page suivante : la valeur `next_cursor` de l'appel précédent. |
| `limit` | entier | non | Le nombre d'éléments rendus, de 1 à 100. 20 par défaut. |

## `create_inbox`

Crée une boîte `username@domaine` sur un domaine d'envoi de l'espace. Elle reçoit tout de suite ; ses envois démarrent au premier palier. Permission : `manage_inboxes`. L'espace doit être vérifié.

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `username` | texte | oui | La partie avant `@` : minuscules, chiffres, point, tiret ou souligné, 64 caractères au plus ; elle commence par une lettre ou un chiffre. Sur le domaine commun : 3 à 32 caractères, et une adresse déjà attribuée ne se réattribue pas. |
| `domain` | texte | non | Un domaine d'envoi de l'espace. Absent : le premier, le sien d'abord s'il en a un de vérifié (voir `inbox_status`, `tenant.domains`). |
| `display_name` | texte | oui | Le nom affiché dans « De : ». Une ligne, 100 caractères au plus, sans `<`, `>` ni guillemet droit. |

```text
Boîte accueil@exemple.fr créée (inb_5c1e8b3a7d0f42c69e2b4a8d1f6c0e37). Elle reçoit dès maintenant. Envois en réchauffage : 5 par jour cette semaine, puis 10, 15, 20 (plafond 20 par jour). Créneau : du lundi au vendredi, de 9 h à 18 h, heure de Paris, jours fériés exclus.
```

- **Avant le paiement, l'espace n'a qu'une boîte** : une seconde est refusée avec le code `payment_required`.
- **Au plafond du forfait**, la création est refusée avec le code `inbox_limit`. La piste donne le nombre de boîtes et le prix du forfait suivant, et la façon d'y passer tout de suite : `subscribe` avec `plan`. Voir [Prix et paiement](https://escouade.io/offre).
- Les adresses de service (`postmaster`, `abuse`, `support`, `admin`, `noreply`…) sont réservées : code `reserved_username`. Sur le domaine commun, la liste est plus large.
- Sur un domaine enregistré par l'espace, la boîte ne se crée qu'une fois le domaine vérifié. C'est d'une telle boîte que part un premier message. Voir [Domaines](https://escouade.io/mail/docs/domaines.md).
- Une boîte créée sur le domaine commun, `subagentmail.fr`, ne fait que répondre à qui lui a écrit.
- Refus possibles : `space_unverified`, `payment_required`, `reserved_username`, `domain_not_allowed`, `no_sending_domain`, `domain_not_verified`, `domain_suspended`, `inbox_limit`, `inbox_creation_limit`, `address_taken`, `provisioning_failed`. Voir [Erreurs](https://escouade.io/mail/docs/erreurs.md).

## `update_inbox`

Change le nom affiché d'une boîte, celui que ses destinataires lisent dans « De : ». L'adresse ne change pas. Permission : `manage_inboxes`.

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `inbox_id` | identifiant `inb_…` | oui | La boîte à renommer. |
| `display_name` | texte | oui | Le nouveau nom. Une ligne, 100 caractères au plus, sans `<`, `>` ni guillemet droit. |

- Le nouveau nom vaut pour les messages écrits ensuite. Un brouillon ou un message en file garde le nom sous lequel il a été écrit : ce qu'un humain a relu est ce qui part.

## `delete_inbox`

Supprime une boîte : ses brouillons et ses messages en file sont annulés, et son compte de messagerie est supprimé. Les fils restent lisibles. Irréversible. Permission : `manage_inboxes`.

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `inbox_id` | identifiant `inb_…` | oui | La boîte à supprimer. |
| `confirm` | booléen | oui | Doit valoir `true` : la suppression est irréversible. |

- Une boîte suspendue ne se supprime pas par l'outil : l'appel est refusé avec le code `inbox_suspended`.
- Supprimer une boîte puis la recréer ne remet rien à zéro : la règle de doublon suit l'adresse, et les créations sont plafonnées sur 7 jours, boîtes supprimées comprises (code `inbox_creation_limit`).

## Une boîte suspendue

Le coupe-circuit suspend une boîte au-delà de 5 % de rebonds (3 % pendant la montée progressive) ou de 0,1 % de plaintes. Tout envoi est alors refusé avec le code `inbox_suspended`, et la raison est écrite dans `status_reason`. La boîte continue de recevoir. La reprise est manuelle, par un administrateur d'Escouade Mail : l'humain la demande avec `request_inbox_review`. Voir [Règles d'envoi](https://escouade.io/mail/docs/regles-envoi.md#coupe-circuit).

## `request_inbox_review`

Demande la reprise d'une boîte suspendue. La demande est notée sur la boîte et au journal, et un administrateur d'Escouade Mail décide. Rien ne reprend tout seul, et aucune date n'est promise. Permission : `approve`. L'espace doit être vérifié.

C'est un geste de l'humain : il le demande à son assistant, branché à l'adresse `https://mail.escouade.io/mcp`. La clé rendue par `sign_up` ne porte pas `approve`.

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `inbox_id` | identifiant `inb_…` | oui | La boîte suspendue. |
| `note` | texte | non | Ce que l'humain veut dire à l'administrateur : une ligne, 300 caractères au plus. |

```text
Reprise demandée mardi 13 octobre à 11 h 02 pour la boîte agent@exemple.fr (inb_3f9c2a7e5b1d4c8e9a0f6b2d7c4e1a95). Un administrateur de Subagent décide : rien ne reprend tout seul, et aucune date n’est promise. D’ici là, la boîte reçoit toujours, et n’envoie pas.
```

- **Avant de demander, corrigez ce qui a causé la suspension** : `status_reason` le dit (adresses mortes, plaintes).
- **Redemander ne change rien de plus** : la première demande reste, avec sa date.
- **Une boîte qui n'est pas suspendue** : refus `inbox_not_suspended`.