# Pour les agents

> Cette page s'adresse à un agent IA qui découvre Subagent Mail. Elle dit où se brancher, quoi appeler d'abord, ce qu'il ne faut pas faire, et liste tous les outils.

## Lire ce site

- Chaque page existe en Markdown : ajoutez `.md` à son adresse. `/docs/boites` devient `/docs/boites.md` ; l'accueil est `/index.md`.
- La carte du site est sur [/llms.txt](https://subagent.fr/llms.txt).
- La référence produite par le serveur fait foi, et se lit sans clé : `https://api.subagent.fr/llms.txt` (les outils et les règles) et `https://api.subagent.fr/openapi.json` (les schémas).

## Se brancher

1. **L'adresse** : `https://api.subagent.fr/mcp`, en Streamable HTTP.
2. **Sans clé**, vous ne voyez qu'un outil : `sign_up`. Appelez-le avec `username` (le nom de votre boîte) et `human_email` (l'e-mail de la personne pour qui vous travaillez).
3. **Gardez la clé rendue** (`api_key`, de la forme `sak_…`) : elle ne s'affiche qu'une fois. Elle se présente dans l'en-tête `Authorization: Bearer sak_…`.
4. **Demandez à votre humain le code à 6 chiffres** qu'il vient de recevoir par e-mail, et passez-le à `verify`.
5. **Si vous avez déjà une clé**, ne vous réinscrivez pas.

Bêta privée : si l'e-mail de votre humain n'est pas invité, `sign_up` répond `invitation_required`. Dites-lui d'écrire à `contact@subagent.fr` pour demander une invitation.

Le détail, avec les réponses des outils : [Démarrer](https://subagent.fr/docs/demarrer.md).

## Les règles à connaître

1. **Commencez par `inbox_status`.** Il rend l'espace, les permissions de la clé, le créneau d'envoi, les limites d'essai et le quota du jour de chaque boîte.
2. **`send_email` écrit un premier message ; `reply_to_thread` répond ou relance dans un fil.** `send_email` n'accepte pas de `thread_id`.
3. **Rien ne part tout de suite.** Un message part dans le créneau de l'espace, dans la limite du quota du jour de sa boîte, avec un étalement entre deux envois.
4. **Un message retenu n'est pas une erreur.** Quota atteint ou envoi hors créneau : le message reste en file (`queued`) et la réponse donne le départ au plus tôt. Ne le renvoyez pas.
5. **Seule une réponse à un correspondant qui a déjà écrit part sans attendre le créneau.**
6. **Vous ne validez pas vos envois.** Avec `requires_approval`, ou si l'espace l'impose, le message reste brouillon jusqu'à ce qu'un humain le valide avec une clé qui porte `approve`.
7. **Un correspondant qui demande à ne plus être contacté se bloque** avec `add_suppression`. Une réponse « STOP » le fait déjà.
8. **Un refus se suit, il ne se contourne pas.** Il porte un `code` stable et une piste (`hint`). Voir [Erreurs](https://subagent.fr/docs/erreurs.md).
9. **Passez une `idempotency_key` à chaque envoi**, pour réessayer sans doublon.
10. **Lisez les réponses** avec `list_threads` (`status` = `replied`), puis `get_thread`.

## Ce qu'il faut dire à votre humain

- Le service est en bêta privée, sur invitation. Aucun prix n'est publié : n'en citez aucun.
- Le service ne promet aucun résultat de remise. Il dit ce qui est parti, remis ou revenu.
- La boîte d'essai est limitée : au plus 3 destinataires distincts la première heure, 5 le premier jour, 10 la première semaine. Dites-le avant d'accepter une mission plus large.
- Ce qui est marqué [à venir] dans cette documentation n'est pas disponible. Ne le présentez pas comme tel.

## Tous les outils

Un agent ne voit que les outils que sa clé autorise. Quand plusieurs permissions sont citées, une seule suffit.

| Outil | Accès | Ce qu'il fait | Détail |
|---|---|---|---|
| `sign_up` | sans clé | Ouvre un espace : rend une clé et une boîte d'essai. | [Démarrer](https://subagent.fr/docs/demarrer.md#inscription) |
| `verify` | toute clé | Vérifie l'espace avec le code à 6 chiffres, et ouvre l'envoi. | [Démarrer](https://subagent.fr/docs/demarrer.md#verification) |
| `attach_human` | toute clé | Rattache l'e-mail de l'humain, ou lui renvoie un code. | [Démarrer](https://subagent.fr/docs/demarrer.md#verification) |
| `inbox_status` | toute clé | Dit où l'on est : espace, permissions, créneau, quota du jour de chaque boîte. | [Boîtes](https://subagent.fr/docs/boites.md#inbox_status) |
| `list_inboxes` | toute clé | Liste les boîtes de la clé. | [Boîtes](https://subagent.fr/docs/boites.md#list_inboxes) |
| `create_inbox` | `manage_inboxes` | Crée une boîte sur un domaine de l'espace. | [Boîtes](https://subagent.fr/docs/boites.md#create_inbox) |
| `delete_inbox` | `manage_inboxes` | Supprime une boîte. Irréversible. | [Boîtes](https://subagent.fr/docs/boites.md#delete_inbox) |
| `add_domain` | `manage_inboxes` | Enregistre un domaine et rend les enregistrements DNS à publier. | [Domaines](https://subagent.fr/docs/domaines.md#add_domain) |
| `verify_domain` | `manage_inboxes` | Contrôle les enregistrements DNS d'un domaine. | [Domaines](https://subagent.fr/docs/domaines.md#verify_domain) |
| `list_domains` | `manage_inboxes` ou `read` | Liste les domaines de l'espace et leur état. | [Domaines](https://subagent.fr/docs/domaines.md#list_domains) |
| `remove_domain` | `manage_inboxes` | Retire un domaine. Irréversible. | [Domaines](https://subagent.fr/docs/domaines.md#remove_domain) |
| `send_email` | `send` | Écrit un premier message à un destinataire. | [Messages](https://subagent.fr/docs/messages.md#send_email) |
| `list_threads` | `read` | Liste les fils, les plus récents d'abord. | [Fils](https://subagent.fr/docs/fils.md#list_threads) |
| `get_thread` | `read` | Lit un fil en entier. | [Fils](https://subagent.fr/docs/fils.md#get_thread) |
| `reply_to_thread` | `send` | Répond ou relance dans un fil. | [Fils](https://subagent.fr/docs/fils.md#reply_to_thread) |
| `get_message` | `read` | Lit un message et son journal. | [Messages](https://subagent.fr/docs/messages.md#get_message) |
| `list_drafts` | `read` ou `approve` | Liste les brouillons à valider. | [Brouillons et validation](https://subagent.fr/docs/brouillons.md#list_drafts) |
| `update_draft` | `send` ou `approve` | Corrige un brouillon. | [Brouillons et validation](https://subagent.fr/docs/brouillons.md#update_draft) |
| `approve_message` | `approve` | Valide un brouillon : il passe en file. | [Brouillons et validation](https://subagent.fr/docs/brouillons.md#approve_message) |
| `cancel_message` | `send` ou `approve` | Annule un brouillon ou un message en file. | [Messages](https://subagent.fr/docs/messages.md#cancel_message) |
| `add_suppression` | `send` ou `approve` | Bloque une adresse ou un domaine. | [Désinscription et blocages](https://subagent.fr/docs/desinscription.md#add_suppression) |
| `remove_suppression` | `approve` | Lève un blocage ajouté à la main. | [Désinscription et blocages](https://subagent.fr/docs/desinscription.md#remove_suppression) |
| `list_suppressions` | `read` | Liste les adresses et domaines bloqués. | [Désinscription et blocages](https://subagent.fr/docs/desinscription.md#list_suppressions) |

`verify` et `attach_human` ne servent qu'avant la vérification de l'espace. `create_inbox`, `send_email`, `reply_to_thread`, `add_domain`, `verify_domain` et `remove_domain` demandent un espace vérifié.

## Les formes

- **Identifiants** : `inb_…` (boîte), `thr_…` (fil), `msg_…` (message), suivis de 32 caractères hexadécimaux. Passez-les tels que les outils les rendent.
- **Dates** : ISO 8601 avec fuseau, à l'heure de Paris, par exemple `2026-10-13T09:00:00+02:00`. En entrée, une heure de Paris sans fuseau (`2026-10-13T09:00`) est acceptée.
- **Listes** : `items` et `next_cursor`. Repassez `next_cursor` dans `cursor` pour la page suivante ; `limit` va de 1 à 100, 20 par défaut.
- **Résultats** : un texte lisible en français, et un objet structuré (`structuredContent`). En HTTP, la réponse est cet objet.
- **Refus** : `{"error": {"code", "message", "hint"}}` en HTTP ; un résultat `isError` par MCP.

## Quand utiliser Subagent Mail

- Vous avez besoin de votre propre adresse e-mail pour écrire à des personnes, recevoir leurs réponses et y répondre dans le même fil : support, prise de rendez-vous, inscription à des services, suivi de dossiers, prospection.
- Le rythme des envois, les heures et la désinscription doivent être appliqués par le serveur, pas par votre prompt.
- Votre humain veut relire et valider vos envois depuis son assistant.

## Quand ne pas l'utiliser

- E-mails transactionnels d'une application (connexion, factures, notifications).
- Envois en masse, lettres d'information, campagnes : une boîte démarre à 5 e-mails par jour et monte à 20 en quatre semaines.
- Accès IMAP ou SMTP à la boîte, pièces jointes, plusieurs destinataires par message : non proposés.