Démarrer

Les réponses d’outils ci-dessous sont des exemples, au format du serveur. Les noms, adresses et identifiants sont fictifs.

Ce qu’il vous faut

• Une invitation. Subagent Mail est en bêta privée : seul un e-mail invité reçoit le code de vérification. Pour demander une invitation, écrivez à contact@subagent.fr.
• Un client MCP qui parle Streamable HTTP : Claude Code, Cursor, ou le vôtre.
• Assistants en ligne (claude.ai, ChatGPT) : le connecteur OAuth 2.1 est [ à venir ].

1. Ajoutez le serveur MCP, sans clé

Une seule adresse : https://api.subagent.fr/mcp.

claude mcp add \
  --transport http subagent \
  https://api.subagent.fr/mcp

{
  "mcpServers": {
    "subagent": {
      "url": "https://api.subagent.fr/mcp"
    }
  }
}

{
  "mcpServers": {
    "subagent": {
      "type": "http",
      "url": "https://api.subagent.fr/mcp"
    }
  }
}

Sans clé, le serveur ne montre qu’un outil : sign_up. Tout le reste demande la clé qu’il rend.

2. Votre agent s’inscrit

Demandez-le-lui : « Inscris-toi à Subagent Mail. Mon e-mail est marie@exemple.fr. » Il appelle sign_up.

Espace ouvert. Votre boîte : atelier-exemple@subagentmail.fr (inb_3f9c2a7e5b1d4c8e9a0f6b2d7c4e1a95). Elle reçoit dès maintenant ; elle n’enverra qu’une fois l’espace vérifié.

Votre clé (affichée une seule fois, gardez-la en lieu sûr) : sak_…
Pour l’utiliser : en-tête « Authorization: Bearer <clé> » sur https://api.subagent.fr/mcp, ou sur POST https://api.subagent.fr/v1/{opération}.

Un code à 6 chiffres vient de partir à m•••@exemple.fr (valable 24 heures). Demandez-le à votre humain, puis appelez verify avec votre clé.

Une fois l’espace vérifié, l’envoi s’ouvre avec les limites d’essai du domaine commun : au plus 3 destinataires distincts la première heure, 5 le premier jour, 10 la première semaine.

Ce que rend sign_up, en objet structuré : api_key, space_id, status (unverified), inbox, human_email (masqué), code_sent, code_expires_at, mcp_url, trial_limits.

• La clé ne s’affiche qu’une fois. Le serveur n’en garde qu’une empreinte. Elle porte send, read et manage_inboxes. Elle ne porte pas approve : voir Brouillons et validation.
• L’e-mail de l’humain est une vraie adresse, hors de Subagent : ni une boîte Subagent, ni un domaine d’exemple.
• Pendant la bêta, un e-mail qui n’est pas invité est refusé avec le code invitation_required. sign_up sans human_email ouvre quand même une boîte qui reçoit ; attach_human rattachera l’humain une fois invité.
• Si vous avez déjà une clé, ne vous réinscrivez pas : utilisez-la.

3. Rebranchez le serveur avec la clé

Rangez la clé hors du code, dans une variable d’environnement, puis déclarez-la au client MCP : en-tête Authorization: Bearer suivi de la clé.

export SUBAGENT_KEY="sak_…"

claude mcp remove subagent
claude mcp add \
  --transport http subagent \
  https://api.subagent.fr/mcp \
  --header "Authorization: Bearer $SUBAGENT_KEY"

{
  "mcpServers": {
    "subagent": {
      "url": "https://api.subagent.fr/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SUBAGENT_KEY}"
      }
    }
  }
}

{
  "mcpServers": {
    "subagent": {
      "type": "http",
      "url": "https://api.subagent.fr/mcp",
      "headers": {
        "Authorization": "Bearer ${SUBAGENT_KEY}"
      }
    }
  }
}

Avec la clé, votre agent voit les outils que ses permissions ouvrent. sign_up n’y figure plus.

4. Donnez le code à votre agent

Vous recevez un e-mail avec un code à 6 chiffres, valable 24 heures. Donnez-le à votre agent : il appelle verify.

Espace vérifié : l’envoi est ouvert. Limites d’essai des boîtes du domaine commun : au plus 3 destinataires distincts la première heure, 5 le premier jour, 10 la première semaine, puis 10 par semaine. Réécrire à un destinataire déjà compté ne prend pas de place. Pour en sortir, envoyez de votre propre domaine : add_domain. Le quota de chaque boîte (réchauffage), le créneau d’envoi et les autres règles s’appliquent toujours : inbox_status les donne.

Un code vaut 24 heures et dix essais. Si le code s’est perdu, a expiré, ou si l’adresse est à corriger, l’agent appelle attach_human.

attach_human renvoie un code à la même adresse, ou la remplace (deux fois au plus). Il attend 60 secondes entre deux codes, et n’en envoie pas plus de cinq pour un même espace. verify et attach_human ne servent qu’avant la vérification : ensuite, ils disparaissent de la liste d’outils.

5. Regardez où vous en êtes

Demandez : « Où en est ma boîte ? » Votre agent appelle inbox_status, le point de départ de toute session.

Espace Atelier Exemple (marque Subagent), 13 octobre 2026. Clé « Atelier Exemple » : send, read, manage_inboxes.
Limites d’essai (boîtes du domaine commun) : 0 sur 3 destinataires distincts la première heure ; 5 à partir de mardi 13 octobre à 15 h 20. Réécrire à un destinataire déjà compté ne prend pas de place.
Créneau d’envoi : du lundi au vendredi, de 9 h à 18 h, heure de Paris, jours fériés exclus.
Boîte atelier-exemple@subagentmail.fr (inb_3f9c2a7e5b1d4c8e9a0f6b2d7c4e1a95) — active
  Quota du jour : 0/5 envoyés, 5 restants (semaine 1 du réchauffage, palier de 5 par jour).

« Réchauffage » est le mot du serveur pour la montée progressive : 5 e-mails par jour la première semaine, puis 10, 15 et 20.

6. Écrivez un premier e-mail

« Écris à Nadia Morel pour déplacer le rendez-vous de jeudi, et laisse le message en brouillon. » Votre agent appelle send_email avec inbox_id, to, subject, text, et requires_approval.

Brouillon msg_7f2a91c4e8b34d0fa6c25e1b9d3f7a48 dans le fil thr_0e5a7c2b9f1d48e6a3c7b5d0e2f9a814 : de atelier-exemple@subagentmail.fr à nadia.morel@exemple.com, « Rendez-vous de jeudi ». Il attend une validation humaine : un humain, avec une clé qui porte approve, le valide (approve_message) ou le corrige (update_draft). Rien ne part avant.

Sans requires_approval, le message entre en file (queued) et part dans le créneau, selon le quota du jour de la boîte. La réponse donne l’heure de départ au plus tôt.

Message msg_7f2a91c4e8b34d0fa6c25e1b9d3f7a48 en file dans le fil thr_0e5a7c2b9f1d48e6a3c7b5d0e2f9a814 : de atelier-exemple@subagentmail.fr à nadia.morel@exemple.com, « Rendez-vous de jeudi ». Départ au plus tôt : mardi 13 octobre à 14 h 31. Quota du jour de la boîte : 0/5 (semaine 1 du réchauffage, palier de 5 par jour).

Sans MCP : la même inscription en HTTP

Chaque outil existe en POST https://api.subagent.fr/v1/{opération}. sign_up est le seul qui s’appelle sans clé.

curl -X POST https://api.subagent.fr/v1/sign_up \
  -H "Content-Type: application/json" \
  -d '{"username": "atelier-exemple", "human_email": "marie@exemple.fr"}'

curl -X POST https://api.subagent.fr/v1/verify \
  -H "Authorization: Bearer $SUBAGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"otp_code": "482913"}'

La réponse est l’objet structuré de l’outil. Une erreur a la forme {"error": {"code", "message", "hint"}}.

Ce que votre agent doit savoir

• Un quota atteint ou un envoi hors des heures ouvrées n’est pas une erreur : le message attend, et la réponse donne l’heure de départ au plus tôt. Il ne faut pas le renvoyer.
• Un refus porte un code stable, un message en français et une piste (hint). La piste se suit, elle ne se contourne pas. Voir Erreurs.
• Une idempotency_key par envoi permet de réessayer sans doublon. Voir Messages.

Ensuite

• Boîtes : la boîte d’essai, ses limites, et ce que rend inbox_status.
• Règles d’envoi : ce qui retient, ce qui refuse.
• Domaines : envoyer depuis votre domaine.