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

# Connector for online assistants

> The connector connects a human's assistant to their space, with no key to copy. Its address: `https://mail.escouade.io/mcp`. The human signs in with their Escouade account, chooses their space and authorises. Without a space, they open one on the same page. This is how they review and approve their agent's drafts.

## Two addresses, one server

| Address | For whom | Without a key or token |
|---|---|---|
| `https://api.subagent.fr/mcp` | An agent, with its `sak_…` key in a header. | The server shows a single tool: `sign_up`. |
| `https://mail.escouade.io/mcp` | A human's online assistant: Claude, ChatGPT, or any assistant that connects an MCP server through OAuth. | The server asks for a sign-in: the assistant opens the authorisation page. |
| `https://api.subagent.fr/connect` | Connectors set up before 20 October 2026: they stay there, with nothing to change. | The same path, in Escouade Mail's name. |

The tools, their parameters and their responses are the same at all three addresses.

## Before connecting

- **You need an Escouade account**, at an e-mail address outside Escouade Mail. An existing user signs in with the same address: they find their space again.
- **With a verified space**, the human finds it again. It is the address the agent gave as `human_email`, which received the verification code. See [Getting started](https://escouade.io/en/mail/docs/demarrer.md).
- **Without a space**, the human opens one on the sign-in page. No agent is needed to sign up.

## Connecting your assistant

1. **Add the connector.** In their assistant, the human adds a connector, or remote MCP server, and pastes the address `https://mail.escouade.io/mcp`. The exact gesture depends on the assistant: [Claude](https://escouade.io/en/mail/docs/brancher/claude.md), [ChatGPT](https://escouade.io/en/mail/docs/brancher/chatgpt.md).
2. **Open the Escouade Mail page.** The assistant opens an Escouade Mail page, on `mail.escouade.io`.
3. **Sign in with the Escouade account.** “Continuer avec Escouade” (continue with Escouade): the account proves the address, once for all of Escouade's applications. This is Escouade's sign-in: Google and Microsoft do not replace it. As a fallback, if the account does not answer for example, the page also offers the e-mail address and a 6-digit code (five attempts, ten minutes): the e-mail opens in the same browser, “Continuer la connexion” (continue signing in).
4. **Choose the space and authorise.** The page shows the application requesting access, the address it returns to, the space concerned and what the application will be able to do. The human authorises, or refuses. Without a space, they open one: see below.

Good to know:

- **Through e-mail, the page gives the same answer to any address**, known or not. An e-mail goes to the human of a verified space. It also goes to an address without a space, within the sign-up limits, and never to an Escouade Mail inbox.
- **The button in the e-mail only works in the browser that started the sign-in.** Opened elsewhere, or forwarded to someone, it opens nothing: the code remains, to copy onto the page.
- **The browser is recognised for thirty days.** Once the address is proven, the next sign-in in this browser goes straight to authorisation: steps 2 and 3 are skipped. “Ce n'est pas votre adresse ? En changer” (not your address? change it), at the bottom of the page, forgets it. Recognising a browser grants no access: each application still has to be authorised.
- **The request is valid for 15 minutes.** After that, it has to be started again from the assistant.
- **The application's name comes from the application itself.** Only the return address says where the access goes. When that address is not a recognised service, the page says so.
- **No key is shown or copied.** The assistant receives tokens, of which the server only keeps a fingerprint.

## Opening a space without an agent

When the address is proven and no space is attached to it, the page offers to open one.

1. **Choose the name of the first inbox.** The page suggests one, taken from the human's address; they can change it. The address will be `name@subagentmail.fr`. The name is 3 to 32 characters: lowercase letters, digits, dot, hyphen or underscore.
2. **Read what the application will be able to do**, and the address it returns to.
3. **Choose “Ouvrir mon espace et autoriser”** (open my space and authorise). The space opens and the assistant is connected to it, in the same gesture.

- **The space opens already verified**: the human's address has just been proven. There is no second code.
- **It has no agent key.** The assistant reads and writes in it through the connector, with what the human authorised.
- **The inbox receives from the moment it opens.** To write to people other than the human, a plan is needed: the assistant gives its link, with `subscribe`. See [Pricing and payment](https://escouade.io/en/pricing).
- **The checks are those of `sign_up`**: the name's format, reserved names, names already taken, sign-up limits. The page says why a name is refused. See [Limits](https://escouade.io/en/mail/docs/limites.md#inscription).
- **An agent working alone opens its own space**, with `sign_up`, at `https://api.subagent.fr/mcp`. To have an agent and approve from their assistant, the human lets the agent sign up first with their e-mail, then finds that space again when signing in.

## What the human grants

The authorisation page lists what the application will be able to do, based on the permissions it requests.

| Permission | What the page says about it |
|---|---|
| `read` | Read your inboxes, your threads and your messages. |
| `send` | Write and reply from your inboxes, within the space's sending rules. |
| `approve` | Approve or cancel pending drafts: what you approve in the assistant leaves. |
| `manage_inboxes` | Create and delete inboxes. |

An assistant that asks for nothing specific asks for all four. With `approve`, the human approves drafts (`approve_message`), lifts a manual block (`remove_suppression`) and cancels the plan (`cancel_subscription`). The agent's key does not carry this permission. See [Keys and permissions](https://escouade.io/en/mail/docs/cles.md#humain).

In a message's log, the assistant's access carries the application's name and the human's e-mail: “Claude (marie@example.com)”, for example.

## Removing access

Access lasts until the human removes it. To end it, they disconnect the connector in their assistant. Connecting the same assistant again resumes the same connection, with the permissions of the new consent.

## What the server tells the agent

An agent does not have `approve`. When it leaves a draft, the response tells it where its human approves it:

```text
Brouillon msg_7f2a91c4e8b34d0fa6c25e1b9d3f7a48 dans le fil thr_0e5a7c2b9f1d48e6a3c7b5d0e2f9a814 : de agent@exemple.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.
```

For an agent:

- **Give your human this address**, not yours: `https://api.subagent.fr/mcp` is the agents' address.
- **Ask them for neither their key, nor their account, nor their sign-in code.** They sign in on the Escouade Mail page, not in the conversation.
- **Tell them yourself** that a draft is waiting: the server sends them no notice.

The full path: [Approve an agent's sends](https://escouade.io/en/mail/docs/guide-validation.md).

## For those building a client

| Topic | What the server does |
|---|---|
| Protocol | OAuth 2.1, with PKCE (`S256`) required. Tokens are opaque. |
| Discovery | Without a token, `https://mail.escouade.io/mcp` answers 401 with the address of the resource metadata (RFC 9728): `https://mail.escouade.io/.well-known/oauth-protected-resource/mcp`. The authorisation server describes itself at `https://mail.escouade.io/.well-known/oauth-authorization-server` (RFC 8414). Each address has its own issuer: Escouade Mail's, `https://mail.escouade.io`; the old one, `https://api.subagent.fr` (resource `https://api.subagent.fr/connect`). A resource from one address is not accepted at the other. |
| Registration | Dynamic (RFC 7591): `https://mail.escouade.io/oauth/register`. |
| Authorisation and tokens | `https://mail.escouade.io/oauth/authorize`, `https://mail.escouade.io/oauth/token`. Grant types: `authorization_code` and `refresh_token`. |
| Revocation | `https://mail.escouade.io/oauth/revoke` (RFC 7009). |
| Scopes | `send`, `read`, `approve`, `manage_inboxes`: a key's permissions. See [Keys and permissions](https://escouade.io/en/mail/docs/cles.md#permissions). |
| Lifetimes | An access token is valid for one hour. A refresh token is valid for 30 days. |

The rest of the MCP protocol is that of `https://api.subagent.fr/mcp`: see [MCP server](https://escouade.io/en/mail/docs/mcp.md).