# 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 Subagent et n'est jamais rendu : la boîte se pilote par les outils, pas par IMAP ni SMTP.
- **Toute boîte reçoit.** Un e-mail reçu ouvre un fil, ou s'ajoute au fil de son correspondant. Voir [Fils](https://subagent.fr/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://subagent.fr/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** : 5 boîtes par défaut. Au-delà, `create_inbox` est refusé avec le code `inbox_limit`.

## La boîte d'essai

`sign_up` ouvre une boîte sur le domaine commun, `subagentmail.fr`. Elle sert à essayer.

- **Avant la vérification** par le code à 6 chiffres, elle reçoit et n'envoie pas : tout envoi est refusé avec le code `space_unverified`.
- **Après**, elle envoie avec des limites d'essai, en plus des règles d'envoi : au plus 3 destinataires distincts la première heure, 5 le premier jour, 10 la première semaine, puis 10 par semaine glissante. Les limites se cumulent : les 5 du premier jour comprennent les 3 de la première heure.
- **Chaque destinataire distinct compte une fois**, y compris un correspondant qui vous a écrit le premier. Lui réécrire ne prend pas de place.
- **Au-delà**, l'envoi est refusé avec le code `trial_limit`. La piste donne le moment où la limite suivante s'ouvre.
- Les limites valent pour tout l'espace, toutes boîtes du domaine commun confondues.

Pour sortir des limites d'essai, enregistrez votre domaine : voir [Domaines](https://subagent.fr/docs/domaines.md).

## `inbox_status`

Le point de départ. Il dit sur quel espace travaille la clé, s'il est vérifié, ses limites d'essai, 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 Exemple), 13 octobre 2026. Clé « claire-assistant » : read, approve.
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 envoie. `false` : ses boîtes reçoivent seulement. |
| `trial` | Les limites d'essai : `limit`, `used`, `window`, `since`, `next_limit`, `next_at`. `null` : aucune. |
| `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. |
| `inboxes` | Les boîtes, chacune avec les champs ci-dessous. |

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.

## 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`. |
| `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. |

## `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. |
| `domain` | texte | non | Un domaine d'envoi de l'espace. Absent : le premier (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.
```

- 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.
- Un espace ouvert par `sign_up` ne crée de boîte que sur le domaine commun, `subagentmail.fr`, tant qu'il n'a pas de domaine à lui. Ces boîtes comptent dans les limites d'essai.
- Sur un domaine enregistré par l'espace, la boîte ne se crée qu'une fois le domaine vérifié. Elle ne compte pas dans les limites d'essai. Voir [Domaines](https://subagent.fr/docs/domaines.md).
- Refus possibles : `domain_not_allowed`, `no_sending_domain`, `inbox_limit`, `address_taken`, `provisioning_failed`. Voir [Erreurs](https://subagent.fr/docs/erreurs.md).

## `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 de Subagent. Voir [Règles d'envoi](https://subagent.fr/docs/regles-envoi.md#coupe-circuit).