# Démarrer > De l'adresse du MCP au premier envoi. À la fin de cette page, votre agent a une clé, une boîte d'essai sur `subagentmail.fr`, et un premier message en file ou en brouillon. 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 Code : ```sh claude mcp add \ --transport http subagent \ https://api.subagent.fr/mcp ``` Cursor (`.cursor/mcp.json`) : ```json { "mcpServers": { "subagent": { "url": "https://api.subagent.fr/mcp" } } } ``` Autre client (`.mcp.json`) : ```json { "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`. | Paramètre | Type | Obligatoire | Description | |---|---|---|---| | `username` | texte | oui | Le nom de la boîte, avant `@` : 3 à 32 caractères, minuscules, chiffres, point, tiret ou souligné ; il commence et finit par une lettre ou un chiffre. Les noms de service (`support`, `admin`, `postmaster`…) et ceux qui commencent par `subagent` sont réservés. | | `human_email` | texte | non | L'e-mail de la personne pour qui l'agent travaille : elle reçoit le code. Sans lui, la boîte reçoit mais n'envoie pas, jusqu'à `attach_human`. | | `agent_name` | texte | non | Le nom de l'agent, affiché dans « De : » et dans l'e-mail du code. 100 caractères au plus. | ```text 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 » 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](https://subagent.fr/docs/brouillons.md). - **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é. ```sh export SUBAGENT_KEY="sak_…" ``` Claude Code : ```sh claude mcp remove subagent claude mcp add \ --transport http subagent \ https://api.subagent.fr/mcp \ --header "Authorization: Bearer $SUBAGENT_KEY" ``` Cursor (`.cursor/mcp.json`) : ```json { "mcpServers": { "subagent": { "url": "https://api.subagent.fr/mcp", "headers": { "Authorization": "Bearer ${env:SUBAGENT_KEY}" } } } } ``` Autre client (`.mcp.json`) : ```json { "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`. | Paramètre | Type | Obligatoire | Description | |---|---|---|---| | `otp_code` | texte | oui | Le code à 6 chiffres reçu par l'humain. | ```text 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`. | Paramètre | Type | Obligatoire | Description | |---|---|---|---| | `human_email` | texte | oui | L'e-mail de l'humain : il reçoit un nouveau code. Le code précédent ne vaut plus. | `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. ```text 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`. ```text 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. ```text 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é. ```sh curl -X POST https://api.subagent.fr/v1/sign_up \ -H "Content-Type: application/json" \ -d '{"username": "atelier-exemple", "human_email": "marie@exemple.fr"}' ``` ```sh 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](https://subagent.fr/docs/erreurs.md). - Une `idempotency_key` par envoi permet de réessayer sans doublon. Voir [Messages](https://subagent.fr/docs/messages.md#idempotence). ## Ensuite - [Boîtes](https://subagent.fr/docs/boites.md) : la boîte d'essai, ses limites, et ce que rend `inbox_status`. - [Règles d'envoi](https://subagent.fr/docs/regles-envoi.md) : ce qui retient, ce qui refuse. - [Domaines](https://subagent.fr/docs/domaines.md) : envoyer depuis votre domaine.