> Pour un agent : la carte de la documentation d'Escouade Mail est sur https://escouade.io/mail/docs/llms.txt ; chaque page existe en Markdown, à la même adresse suffixée `.md`.

# Démarrer

> De l'adresse du MCP au premier e-mail. À la fin de cette page, votre agent a une clé et une première boîte sur `subagentmail.fr`, et il vous a écrit. Les deux dernières étapes ouvrent l'envoi à d'autres que vous : le paiement, puis votre domaine.

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

Sans agent ? Depuis Claude ou ChatGPT, vous ouvrez votre espace sur la page de connexion : [Brancher Claude](https://escouade.io/mail/docs/brancher/claude.md), [Brancher ChatGPT](https://escouade.io/mail/docs/brancher/chatgpt.md).

## Ce qu'il vous faut

- **Un client MCP** qui parle Streamable HTTP : Claude Code, Cursor, ou le vôtre. Assistant par assistant : [Brancher mon agent](https://escouade.io/mail/docs/brancher.md).
- **Une adresse e-mail à vous**, hors d'Escouade Mail : elle reçoit le code à 6 chiffres.
- **Un endroit où garder la clé** : elle ne s'affiche qu'une fois.

Le service est payant. Avant le paiement, la boîte reçoit, prépare des brouillons et n'écrit qu'à vous : les six premières étapes ne coûtent rien. Voir [Prix et paiement](https://escouade.io/offre).

## 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 à Escouade 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 contiennent `subagent` sont réservés. Un nom déjà attribué ne se réattribue pas. |
| `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. 60 caractères au plus : lettres, chiffres, espaces, tirets et apostrophes. |

```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 <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é, la boîte prépare des brouillons et écrit à votre humain (test: true). Pour écrire à des tiers, l’espace doit avoir un forfait : 9 € par mois : 2 boîtes, 800 e-mails par mois ; 19 € par mois : 5 boîtes, 2 000 e-mails par mois ; 49 € par mois : 15 boîtes, 6 000 e-mails par mois. billing_status dit où il en est.
```

L'objet structuré porte notamment `api_key`, `space_id`, `status` (`unverified`), `inbox`, `human_email` (masqué), `code_sent`, `code_expires_at` et `mcp_url`.

- **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://escouade.io/mail/docs/brouillons.md).
- **L'e-mail de l'humain est une vraie adresse**, hors d'Escouade Mail : ni une boîte Escouade Mail, ni un domaine d'exemple.
- **Sans `human_email`**, `sign_up` ouvre une boîte qui reçoit ; `attach_human` rattache l'humain ensuite.
- **Si vous avez déjà une clé**, ne vous réinscrivez pas : utilisez-la.
- **Un espace jamais vérifié est effacé** sept jours après son ouverture, avec sa boîte.

## 3. Rebranchez le serveur avec la clé

Le serveur lit la clé à chaque requête : la connexion ouverte sans clé ne montre toujours que `sign_up`. 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.

Un agent qui peut faire une requête HTTP n'a pas besoin de ce rebranchement pour continuer : il appelle `POST https://api.subagent.fr/v1/verify` avec l'en-tête. Voir [Clés et permissions](https://escouade.io/mail/docs/cles.md#apres-sign-up).

## 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é. La boîte reçoit, prépare des brouillons et écrit à votre humain (send_email avec test: true). Pour écrire à des tiers, l’espace doit avoir un forfait : 9 € par mois : 2 boîtes, 800 e-mails par mois ; 19 € par mois : 5 boîtes, 2 000 e-mails par mois ; 49 € par mois : 15 boîtes, 6 000 e-mails par mois. billing_status dit où il en est.
```

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.
Aucun forfait en cours : la boîte reçoit, prépare des brouillons et n’écrit qu’à son humain (test: true). subscribe remet le lien de paiement à donner à votre humain.
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. Tous les mots : [Glossaire](https://escouade.io/mail/docs/glossaire.md).

## 6. Faites-vous écrire un premier e-mail

« Écris-moi un premier e-mail. » Votre agent appelle `send_email` avec `inbox_id`, `to` (votre adresse), `subject`, `text`, et `test` = `true`. Un envoi de test ne part que vers vous, ou vers une autre boîte de l'espace.

```text
Message msg_1a6e4c9f2b8d40e7a5c3f1d9b0e6a283 en file dans le fil thr_0e5a7c2b9f1d48e6a3c7b5d0e2f9a814 : de atelier-exemple@subagentmail.fr à marie@exemple.fr, « Premier e-mail ». 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).
```

Le message ne part pas tout de suite : il 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.

Avant le paiement, c'est le seul envoi qui part. Votre agent peut aussi préparer des brouillons pour d'autres destinataires, avec `requires_approval` : ils attendent.

```text
Brouillon msg_7f2a91c4e8b34d0fa6c25e1b9d3f7a48 dans le fil thr_6c3d9e1f0a7b42c58e1d6a9f3b0c7e25 : de atelier-exemple@subagentmail.fr à nadia.morel@exemple.com, « Rendez-vous de jeudi ». Il attend une validation humaine : votre humain (m•••@exemple.fr) branche son assistant (Claude, ChatGPT…) à l’adresse https://mail.escouade.io/mcp, s’y connecte avec cet e-mail, puis relit le brouillon et le valide ou le corrige. Dites-le-lui : aucun avis ne lui est envoyé. Rien ne part avant.
```

## 7. Payez par un lien

« Ouvre l'envoi. » Votre agent appelle `subscribe` et vous remet un lien, valable 72 heures. Sur la page du lien, vous choisissez votre forfait (9 €, 19 € ou 49 € par mois), vous donnez vos coordonnées de facturation, puis vous payez sur la page de Mollie, avec la confirmation de votre banque. Votre agent ne paie jamais.

Ensuite, `billing_status` dit que le forfait est en cours. Le détail : [Prix et paiement](https://escouade.io/offre).

## 8. Enregistrez votre domaine

Une fois le forfait payé, la boîte du domaine commun répond à qui lui a écrit. Pour écrire le premier, il faut une boîte sur votre domaine.

1. Votre agent appelle `add_domain` : il vous rend les enregistrements DNS à publier.
2. Vous les publiez chez l'hébergeur DNS du domaine.
3. Il appelle `verify_domain`, puis `create_inbox` sur ce domaine.

Le détail : [Domaines](https://escouade.io/mail/docs/domaines.md).

## 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://escouade.io/mail/docs/erreurs.md).
- Sans forfait, un envoi à un tiers est refusé avec le code `payment_required`. L'agent ne paie pas : il remet le lien de `subscribe` à son humain.
- Une `idempotency_key` par envoi permet de réessayer sans doublon. Voir [Messages](https://escouade.io/mail/docs/messages.md#idempotence).

## Ensuite

- [Valider les envois d'un agent](https://escouade.io/mail/docs/guide-validation.md) : relire et valider depuis votre assistant, branché à `https://mail.escouade.io/mcp`.
- [Répondre à un correspondant](https://escouade.io/mail/docs/guide-repondre.md) : relever les fils, lire, répondre.
- [Boîtes](https://escouade.io/mail/docs/boites.md) : la première boîte, et ce que rend `inbox_status`.
- [Règles d'envoi](https://escouade.io/mail/docs/regles-envoi.md) : ce qui retient, ce qui refuse.
- [Prix et paiement](https://escouade.io/offre) : les forfaits, les factures, la résiliation.