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

# Connect over HTTP

> Without an MCP client, every tool is called as `POST https://api.subagent.fr/v1/{operation}`: the same arguments in JSON, the same object in return. No route exists that is not a tool.

## 1. Sign up, without a key

`sign_up` is the only tool 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"}'
```

The response carries `api_key`: the key, of the form `sak_…`. **It is shown only once.** It also carries `inbox`, the inbox `atelier-exemple@subagentmail.fr`. A 6-digit code goes to the e-mail given: it is valid for 24 hours.

## 2. Present the key

Store the key in an environment variable. Every following call presents it in a header.

```sh
export SUBAGENT_KEY="sak_…"
```

```http
Authorization: Bearer sak_…
```

## 3. Verify the space

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

Before this code, the inbox receives but does not send.

## 4. See where you stand

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

The response is the object the tool returns over MCP in `structuredContent`: the space, the key's permissions, the sending hours, and for each inbox its daily quota.

## Refusals

A refusal is an HTTP status and an object `{"error": {"code", "message", "hint"}}`. The `code` is stable: it is what a program tests. The lead (`hint`) says what to do. The message is in French, as the server writes it.

```json
{
  "error": {
    "code": "payment_required",
    "message": "Cet espace n’a pas de forfait en cours : sa boîte reçoit, prépare des brouillons et n’écrit qu’à son humain (test: true).",
    "hint": "…"
  }
}
```

Every code, with what to do: [Errors](https://escouade.io/en/mail/docs/erreurs.md).

## Next

- **Pay**: `POST https://api.subagent.fr/v1/subscribe` returns a payment link, to hand to the space's human. See [Pricing](https://escouade.io/en/pricing).
- **The schemas**: `https://api.subagent.fr/openapi.json` (OpenAPI 3.1), readable without a key. One page per tool: [Tool reference](https://escouade.io/en/mail/docs/reference/index.md).
- **The details**: [HTTP API](https://escouade.io/en/mail/docs/api-http.md): pagination, idempotency, rate.
- **SDKs and a command line**: see [Open source](https://escouade.io/en/mail/docs/open-source.md).
- The other assistants: [Connect my agent](https://escouade.io/en/mail/docs/brancher.md).