> Ouverture en cours : l'inscription et le paiement ne sont pas encore ouverts à tous. L'état du jour : https://subagent.fr/docs/etat.md
>
> Pour un agent : la carte du site est sur https://subagent.fr/llms.txt ; chaque page existe en Markdown, à la même adresse suffixée `.md`.

# `create_inbox`

> Crée une boîte e-mail <username>@<domaine> sur un domaine d’envoi de l’espace (son propre domaine vérifié, voir `add_domain` ; sinon le domaine commun ou celui de la marque), et le compte correspondant sur le serveur de messagerie.

## En bref

| Propriété | Valeur |
|---|---|
| Titre | Créer une boîte |
| Outil MCP | `create_inbox`, sur `https://api.subagent.fr/mcp` |
| Appel HTTP | `POST https://api.subagent.fr/v1/create_inbox` |
| Accès | permission `manage_inboxes` |
| État de l'espace | vérifié : sinon, refus `space_unverified` |
| Effet | écriture |
| Vue dans l'assistant | non |

## Ce que fait l'outil

Le serveur décrit l'outil ainsi à l'agent qui se branche :

> Crée une boîte e-mail <username>@<domaine> sur un domaine d’envoi de l’espace (son propre domaine vérifié, voir `add_domain` ; sinon le domaine commun ou celui de la marque), et le compte correspondant sur le serveur de messagerie. La boîte reçoit tout de suite ; ses envois démarrent en réchauffage (5 par jour la première semaine, puis 10, 15, 20). Le nombre de boîtes par espace est plafonné. Le mot de passe est géré par Subagent et n’est jamais rendu.

## Paramètres

`create_inbox` accepte ces paramètres. Un paramètre inconnu est refusé avec le code `invalid_argument`.

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `username` | texte | oui | Partie avant @ (minuscules, chiffres, . _ -), par exemple « prospection » ou « marie.durand ». Sur le domaine commun : 3 à 32 caractères, et une adresse déjà attribuée ne se réattribue pas. |
| `domain` | texte | non | Domaine d’envoi de l’espace. Absent : son premier domaine, le sien d’abord s’il en a un de vérifié (voir `inbox_status`, tenant.domains). |
| `display_name` | texte | oui | Nom affiché dans « De : », par exemple « Marie de Prescriptio ». 100 caractères au plus. |

## Résultat

L'outil rend une boîte. L'objet structuré déclare les champs ci-dessous ; la page de concept les décrit tous : voir [les champs d'une boîte](https://subagent.fr/docs/boites.md#champs).

| Champ | Type | Contenu |
|---|---|---|
| `address` | texte | Adresse e-mail. |
| `display_name` | texte | Nom affiché des envois. |
| `drafts` | entier | Le nombre de brouillons à valider. |
| `id` | texte | Identifiant de la boîte (inb_…). |
| `next_send_at` | texte ou `null` | Prochain départ au plus tôt (ISO 8601). |
| `queued` | entier | Le nombre de messages en file. |
| `quota` | objet | `daily_quota`, `daily_max`, `sent_today`, `remaining_today`. |
| `send_window` | texte | Créneau d’envoi en clair. |
| `shared` | booléen | Boîte du domaine commun, et non d’un domaine de l’espace. |
| `status` | texte | L'état de la boîte. Valeurs : `active`, `suspended`, `deleted`. |
| `status_changed_at` | texte ou `null` | Depuis quand la boîte est dans cet état (ISO 8601) : la date d’une suspension, ou d’une reprise. |
| `status_reason` | texte ou `null` | La raison d'une suspension, sinon `null`. |
| `suspension` | objet ou `null` | Pour une boîte suspendue : review (none, ou requested quand la reprise a été demandée) et `requested_at`. `null` sinon. |
| `warmup` | objet | Réchauffage : semaine, palier du jour, paliers, terminé ou non. |

## Exemple d'appel

Les valeurs sont fictives.

HTTP :

```sh
curl -X POST https://api.subagent.fr/v1/create_inbox \
  -H "Authorization: Bearer $SUBAGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "username": "accueil",
  "domain": "agents.exemple.fr",
  "display_name": "Accueil Atelier Exemple"
}'
```

MCP (`tools/call`) :

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_inbox",
    "arguments": {
      "username": "accueil",
      "domain": "agents.exemple.fr",
      "display_name": "Accueil Atelier Exemple"
    }
  }
}
```

## Refus possibles

| Code | HTTP | Ce qui s'est passé | Que faire |
|---|---|---|---|
| `space_unverified` | 403 | L'espace n'est pas vérifié : ses boîtes reçoivent, mais n'envoient pas. | Demander à l'humain le code à 6 chiffres, puis appeler `verify`. S'il n'a rien reçu, ou si aucun e-mail n'est rattaché à l'espace : `attach_human`. |
| `payment_required` | 402 | L'espace n'a pas de forfait en cours : sa boîte reçoit, prépare des brouillons et n'écrit qu'à son humain. Le refus vaut pour un envoi à un tiers, la validation d'un brouillon, une seconde boîte et `add_domain`. | Appeler `subscribe`, après l'accord de l'humain, et lui remettre le lien de paiement. Ensuite, `billing_status` dit si le forfait est en cours. |
| `reserved_username` | 422 | Ce nom est réservé : adresse de service, ou nom réservé sur le domaine commun. | Choisir le nom de l'agent, d'une personne ou d'une fonction. |
| `domain_not_allowed` | 422 | Le domaine demandé n'est pas un domaine d'envoi de l'espace. Ou, pour `add_domain`, c'est un domaine de Subagent. | Prendre un des domaines donnés par la piste, ou enregistrer un domaine dont vous gérez le DNS. |
| `no_sending_domain` | 409 | L'espace n'a aucun domaine d'envoi. | Prévenir un administrateur de Subagent. |
| `domain_not_verified` | 409 | Le domaine de la boîte n'est pas encore vérifié. | Publier ses enregistrements DNS, puis appeler `verify_domain`. |
| `domain_suspended` | 409 | Un enregistrement DNS exigé a disparu : le domaine est suspendu, ses boîtes n'envoient plus. | Remettre les enregistrements en place (`list_domains` les donne), puis appeler `verify_domain`. |
| `inbox_limit` | 409 | Le plafond de boîtes du forfait est atteint. La piste donne le nombre de boîtes et le prix du forfait suivant. | Supprimer une boîte inutile avec `delete_inbox`, ou passer au forfait suivant : `subscribe` avec `plan` remet le lien à l'humain, qui paie la différence au prorata. Voir [Prix et paiement](https://subagent.fr/docs/prix.md#plus-grand). |
| `inbox_creation_limit` | 429 | Trop de boîtes créées en 7 jours pour l'espace : deux fois le plafond du forfait au plus. Les boîtes supprimées comptent. | Garder ses boîtes plutôt que les supprimer et les recréer. Pour un besoin réel, écrire à `contact@subagent.fr`. |
| `address_taken` | 409 | L'adresse est déjà une boîte. | Choisir un autre `username`. |
| `provisioning_failed` | 502 | Le serveur de messagerie n'a pas créé la boîte, ou n'a pas pris le domaine. | Réessayer dans un instant. Rien n'est perdu. |

S'y ajoutent les refus communs à tous les outils (`unauthorized`, `forbidden`, `invalid_argument`, `rate_limited`, `internal`) : voir [Erreurs](https://subagent.fr/docs/erreurs.md#acces).

## Voir aussi

- [Boîtes : create_inbox](https://subagent.fr/docs/boites.md#create_inbox)
- [Domaines](https://subagent.fr/docs/domaines.md)
- [`list_inboxes`](https://subagent.fr/docs/reference/list_inboxes.md)
- [`delete_inbox`](https://subagent.fr/docs/reference/delete_inbox.md)
- [`add_domain`](https://subagent.fr/docs/reference/add_domain.md)
- [`billing_status`](https://subagent.fr/docs/reference/billing_status.md)
- [Tous les outils](https://subagent.fr/docs/reference/index.md)