# Introduction

> Subagent Mail donne une boîte mail à un agent IA. Il écrit, reçoit et répond avec sa propre adresse, par MCP. Cette documentation est écrite pour l'agent d'abord : chaque page existe en Markdown, à la même adresse suffixée `.md`.

**Statut : bêta privée.** Les inscriptions sont sur invitation. Pour demander une invitation, écrivez à `contact@subagent.fr`.

## En bref

- **Une adresse** : `https://api.subagent.fr/mcp`, un serveur MCP en Streamable HTTP.
- **Sans clé**, le serveur ne montre qu'un outil : `sign_up`. Il ouvre un espace, rend une clé (`sak_…`, affichée une seule fois) et une boîte d'essai sur `subagentmail.fr`.
- **Un humain confirme** : il reçoit par e-mail un code à 6 chiffres, que l'agent passe à `verify`. Avant, la boîte reçoit et n'envoie pas.
- **Le serveur règle les envois** : montée progressive, quota du jour, heures ouvrées, validation humaine, désinscription, coupe-circuit. Voir [Règles d'envoi](https://subagent.fr/docs/regles-envoi.md).
- **Aucune console.** Un humain lit, corrige et valide depuis son assistant, branché au même serveur.

## La consigne à donner à votre agent

Remplacez l'adresse par la vôtre : c'est elle qui reçoit le code.

Consigne :

```text
Branche-toi au MCP de Subagent Mail : https://api.subagent.fr/mcp
Lis d'abord https://subagent.fr/llms.txt.
Inscris-toi avec sign_up : choisis un nom de boîte et donne mon e-mail, marie@exemple.fr, en human_email.
Garde la clé rendue : elle ne s'affiche qu'une fois.
Je te donnerai le code à 6 chiffres que je vais recevoir : passe-le à verify.
```

## Par où commencer

- [Démarrer](https://subagent.fr/docs/demarrer.md) : de l'adresse du MCP au premier envoi.
- [Règles d'envoi](https://subagent.fr/docs/regles-envoi.md) : ce qui retient un message, ce qui le refuse, et à partir de quel seuil.
- [Erreurs](https://subagent.fr/docs/erreurs.md) : chaque code, sa raison, sa suite.
- [Pour les agents](https://subagent.fr/docs/agents.md) : tous les outils sur une page, et les règles à connaître avant le premier appel.

## Les objets

| Objet | Ce que c'est |
|---|---|
| Boîte (`inb_…`) | Une adresse e-mail pilotée par un agent. Elle porte son calendrier de montée progressive et son quota du jour. Toute boîte reçoit. Voir [Boîtes](https://subagent.fr/docs/boites.md). |
| Fil (`thr_…`) | La conversation entre une boîte et un correspondant. Il naît au premier envoi ou au premier e-mail reçu. Voir [Fils](https://subagent.fr/docs/fils.md). |
| Message (`msg_…`) | Entrant ou sortant, dans un fil. Un sortant passe par `draft`, `queued`, `sending`, `sent`, `delivered`. Voir [Messages](https://subagent.fr/docs/messages.md). |
| Brouillon | Un message `draft` : il attend une validation humaine et se corrige tant qu'il n'est pas validé. Voir [Brouillons et validation](https://subagent.fr/docs/brouillons.md). |
| Clé (`sak_…`) | Elle désigne un espace et porte des permissions : `send`, `read`, `approve`, `manage_inboxes`. Elle peut être limitée à certaines boîtes et porter un plafond de messages par jour. |
| Espace | Les boîtes, les fils, les clés et la liste de blocage d'un même client. La clé l'impose : un agent ne peut pas en sortir. |

Les identifiants sont préfixés (`inb_`, `thr_`, `msg_`) et suivis de 32 caractères hexadécimaux. Les dates sont en ISO 8601, à l'heure de Paris, avec leur fuseau.

## Les permissions d'une clé

| Permission | Ce qu'elle ouvre |
|---|---|
| `send` | Envoyer et répondre. |
| `read` | Lire les boîtes, les fils et les messages. |
| `approve` | Valider ou annuler les brouillons. Elle est réservée à un humain : la clé rendue par `sign_up` ne la porte pas. |
| `manage_inboxes` | Créer et supprimer des boîtes. |

Un agent ne voit que les outils que sa clé autorise.

## Deux façons d'appeler

- **MCP** : `https://api.subagent.fr/mcp`, en-tête `Authorization: Bearer sak_…`. Chaque résultat porte un texte lisible en français et un objet structuré (`structuredContent`).
- **HTTP** : chaque outil existe aussi en `POST https://api.subagent.fr/v1/{opération}`, avec les mêmes arguments en JSON et le même objet en réponse. Aucune route n'existe qui ne soit pas un outil.

La référence produite par le serveur fait foi : `https://api.subagent.fr/llms.txt` et `https://api.subagent.fr/openapi.json`.

## Ce qui est à venir

Cette documentation ne décrit comme disponible que ce que le serveur fait. Le reste porte la marque [à venir].

| Sujet | État |
|---|---|
| Inscription par l'agent, boîte d'essai, code de vérification | en service, sur invitation |
| Boîtes, messages, fils, brouillons, liste de blocage | en service |
| Domaines du client (`add_domain`, `verify_domain`) | en service, voir [Domaines](https://subagent.fr/docs/domaines.md) |
| Connecteur pour assistants en ligne (OAuth 2.1) | [à venir] |
| Webhooks réglés par le client | [à venir], voir [Webhooks](https://subagent.fr/docs/webhooks.md) |
| SDK Python et TypeScript, ligne de commande, skills | [à venir], voir [Open source](https://subagent.fr/open-source.md) |
| Prix | aucun n'est publié, voir [Tarifs](https://subagent.fr/tarifs.md) |