> For an agent: the map of this documentation is at https://escouade.io/en/mail/docs/llms.txt; every page exists in Markdown, at the same address with `.md` appended.

# Getting started

> From the MCP address to the first e-mail. By the end of this page, your agent has a key and a first inbox on `subagentmail.fr`, and it has written to you. The last two steps open sending to people other than you: payment, then your domain.

The tool responses below are examples, in the server's format; the server answers in French. Names, addresses and identifiers are fictitious.

No agent? From Claude or ChatGPT, you open your space on the sign-in page: [Connect Claude](https://escouade.io/en/mail/docs/brancher/claude.md), [Connect ChatGPT](https://escouade.io/en/mail/docs/brancher/chatgpt.md).

## What you need

- **An MCP client** that speaks Streamable HTTP: Claude Code, Cursor, or your own. Assistant by assistant: [Connect my agent](https://escouade.io/en/mail/docs/brancher.md).
- **An e-mail address of your own**, outside Escouade Mail: it receives the 6-digit code.
- **Somewhere to keep the key**: it is shown only once.

The service is paid. Before payment, the inbox receives, prepares drafts and only writes to you: the first six steps cost nothing. See [Pricing and payment](https://escouade.io/en/pricing).

## 1. Add the MCP server, without a key

A single address: `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"
    }
  }
}
```

Other client (`.mcp.json`):

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

Without a key, the server shows a single tool: `sign_up`. Everything else needs the key it returns.

## 2. Your agent signs up

Ask it: “Sign up to Escouade Mail. My e-mail is marie@example.com.” It calls `sign_up`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `username` | text | yes | The inbox name, before the `@`: 3 to 32 characters, lowercase letters, digits, dot, hyphen or underscore; it starts and ends with a letter or a digit. Service names (`support`, `admin`, `postmaster`…) and names containing `subagent` are reserved. A name already given out is never given out again. |
| `human_email` | text | no | The e-mail of the person the agent works for: they receive the code. Without it, the inbox receives but does not send, until `attach_human`. |
| `agent_name` | text | no | The agent's name, shown in “From:” and in the code e-mail. 60 characters at most: letters, digits, spaces, hyphens and 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.
```

The structured object carries, among others, `api_key`, `space_id`, `status` (`unverified`), `inbox`, `human_email` (masked), `code_sent`, `code_expires_at` and `mcp_url`.

- **The key is shown only once.** The server only keeps a fingerprint of it. It carries `send`, `read` and `manage_inboxes`. It does not carry `approve`: see [Drafts and approval](https://escouade.io/en/mail/docs/brouillons.md).
- **The human's e-mail is a real address**, outside Escouade Mail: neither an Escouade Mail inbox nor an example domain.
- **Without `human_email`**, `sign_up` opens an inbox that receives; `attach_human` attaches the human afterwards.
- **If you already have a key**, do not sign up again: use it.
- **A space that is never verified is erased** seven days after it was opened, along with its inbox.

## 3. Reconnect the server with the key

The server reads the key on every request: the connection opened without a key still only shows `sign_up`. Keep the key out of your code, in an environment variable, then declare it to the MCP client: an `Authorization: Bearer` header followed by the key.

```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}"
      }
    }
  }
}
```

Other client (`.mcp.json`):

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

With the key, your agent sees the tools its permissions open. `sign_up` is no longer among them.

An agent that can make an HTTP request does not need to reconnect to carry on: it calls `POST https://api.subagent.fr/v1/verify` with the header. See [Keys and permissions](https://escouade.io/en/mail/docs/cles.md#apres-sign-up).

## 4. Give the code to your agent

You receive an e-mail with a 6-digit code, valid for 24 hours. Give it to your agent: it calls `verify`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `otp_code` | text | yes | The 6-digit code the human received. |

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

A code is valid for 24 hours and ten attempts. If the code got lost, expired, or the address needs correcting, the agent calls `attach_human`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `human_email` | text | yes | The human's e-mail: they receive a new code. The previous code stops working. |

`attach_human` sends a new code to the same address, or replaces it (twice at most). It waits 60 seconds between two codes, and sends no more than five for the same space. `verify` and `attach_human` only serve before verification: afterwards, they disappear from the tool list.

## 5. See where you stand

Ask: “How is my inbox doing?” Your agent calls `inbox_status`, the starting point of every 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” is the server's word for warm-up: 5 e-mails a day the first week, then 10, 15 and 20. Every term: [Glossary](https://escouade.io/en/mail/docs/glossaire.md).

## 6. Have a first e-mail written to you

“Write me a first e-mail.” Your agent calls `send_email` with `inbox_id`, `to` (your address), `subject`, `text`, and `test` = `true`. A test send only goes to you, or to another inbox of the space.

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

The message does not leave straight away: it enters the queue (`queued`) and leaves within the sending window, according to the inbox's daily quota. The response gives the earliest departure time.

Before payment, this is the only send that leaves. Your agent can also prepare drafts for other recipients, with `requires_approval`: they wait.

```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. Pay through a link

“Open sending.” Your agent calls `subscribe` and hands you a link, valid for 72 hours. On the link's page, you choose your plan (€9, €19 or €49 a month), enter your billing details, then pay on Mollie's page, with your bank's confirmation. Your agent never pays.

Afterwards, `billing_status` says the plan is active. The details: [Pricing and payment](https://escouade.io/en/pricing).

## 8. Register your domain

Once the plan is paid, the inbox on the shared domain replies to whoever wrote to it. To write first, you need an inbox on your own domain.

1. Your agent calls `add_domain`: it hands you the DNS records to publish.
2. You publish them at the domain's DNS host.
3. It calls `verify_domain`, then `create_inbox` on that domain.

The details: [Domains](https://escouade.io/en/mail/docs/domaines.md).

## Without MCP: the same sign-up over HTTP

Every tool exists as `POST https://api.subagent.fr/v1/{operation}`. `sign_up` is the only one called without a key.

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

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

The response is the tool's structured object. An error has the shape `{"error": {"code", "message", "hint"}}`.

## What your agent should know

- A reached quota or a send outside working hours is not an error: the message waits, and the response gives the earliest departure time. Do not send it again.
- A refusal carries a stable `code`, a `message` in French and a lead (`hint`). The lead is to be followed, not worked around. See [Errors](https://escouade.io/en/mail/docs/erreurs.md).
- Without a plan, a send to a third party is refused with the code `payment_required`. The agent does not pay: it hands the `subscribe` link to its human.
- An `idempotency_key` per send lets you retry without duplicates. See [Messages](https://escouade.io/en/mail/docs/messages.md#idempotence).

## Next

- [Approve an agent's sends](https://escouade.io/en/mail/docs/guide-validation.md): review and approve from your assistant, connected at `https://mail.escouade.io/mcp`.
- [Reply to a correspondent](https://escouade.io/en/mail/docs/guide-repondre.md): collect threads, read, reply.
- [Inboxes](https://escouade.io/en/mail/docs/boites.md): the first inbox, and what `inbox_status` returns.
- [Sending rules](https://escouade.io/en/mail/docs/regles-envoi.md): what holds a message back, what refuses it.
- [Pricing and payment](https://escouade.io/en/pricing): plans, invoices, cancellation.