Pour les agents · Documentation Subagent

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

L’adresse : https://api.subagent.fr/mcp, en Streamable HTTP.
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).
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_….
Demandez à votre humain le code à 6 chiffres qu’il vient de recevoir par e-mail, et passez-le à verify.
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.

Les règles à connaître

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.
send_email écrit un premier message ; reply_to_thread répond ou relance dans un fil. send_email n’accepte pas de thread_id.
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.
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.
Seule une réponse à un correspondant qui a déjà écrit part sans attendre le créneau.
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.
Un correspondant qui demande à ne plus être contacté se bloque avec add_suppression. Une réponse « STOP » le fait déjà.
Un refus se suit, il ne se contourne pas. Il porte un code stable et une piste (hint). Voir Erreurs.
Passez une idempotency_key à chaque envoi, pour réessayer sans doublon.
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
`verify`	toute clé	Vérifie l’espace avec le code à 6 chiffres, et ouvre l’envoi.	Démarrer
`attach_human`	toute clé	Rattache l’e-mail de l’humain, ou lui renvoie un code.	Démarrer
`inbox_status`	toute clé	Dit où l’on est : espace, permissions, créneau, quota du jour de chaque boîte.	Boîtes
`list_inboxes`	toute clé	Liste les boîtes de la clé.	Boîtes
`create_inbox`	`manage_inboxes`	Crée une boîte sur un domaine de l’espace.	Boîtes
`delete_inbox`	`manage_inboxes`	Supprime une boîte. Irréversible.	Boîtes
`add_domain`	`manage_inboxes`	Enregistre un domaine et rend les enregistrements DNS à publier.	Domaines
`verify_domain`	`manage_inboxes`	Contrôle les enregistrements DNS d’un domaine.	Domaines
`list_domains`	`manage_inboxes` ou `read`	Liste les domaines de l’espace et leur état.	Domaines
`remove_domain`	`manage_inboxes`	Retire un domaine. Irréversible.	Domaines
`send_email`	`send`	Écrit un premier message à un destinataire.	Messages
`list_threads`	`read`	Liste les fils, les plus récents d’abord.	Fils
`get_thread`	`read`	Lit un fil en entier.	Fils
`reply_to_thread`	`send`	Répond ou relance dans un fil.	Fils
`get_message`	`read`	Lit un message et son journal.	Messages
`list_drafts`	`read` ou `approve`	Liste les brouillons à valider.	Brouillons et validation
`update_draft`	`send` ou `approve`	Corrige un brouillon.	Brouillons et validation
`approve_message`	`approve`	Valide un brouillon : il passe en file.	Brouillons et validation
`cancel_message`	`send` ou `approve`	Annule un brouillon ou un message en file.	Messages
`add_suppression`	`send` ou `approve`	Bloque une adresse ou un domaine.	Désinscription et blocages
`remove_suppression`	`approve`	Lève un blocage ajouté à la main.	Désinscription et blocages
`list_suppressions`	`read`	Liste les adresses et domaines bloqués.	Désinscription et blocages

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.