create_inbox · Documentation Subagent

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.

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

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

{
  "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.
`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.

`create_inbox`