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

# Domains

> An inbox lives on a domain. The first one is on the shared domain, `subagentmail.fr`: it receives and replies. To write to someone first, you register your own domain: your inboxes carry your name.

## The shared domain

`sign_up` opens an inbox `name@subagentmail.fr`. This domain is shared by every space.

- **Its inboxes receive**, from the moment they are created.
- **Before payment**, they prepare drafts and only write to the space's human.
- **Once the plan is paid, they only reply** to whoever wrote to them. A first message, or a follow-up with no reply, is refused with the code `own_domain_required`.
- Service names (`support`, `contact`, `admin`, `postmaster`…) and names containing `subagent` are reserved there.
- It needs no DNS setting on your side.

See [Pricing and payment](https://escouade.io/en/pricing).

## Your domain, in three steps

1. **Register.** `add_domain` registers the domain and returns the exact list of DNS records to publish.
2. **Publish.** You publish these records at the domain's DNS host. It is the only gesture that happens outside the assistant.
3. **Verify.** `verify_domain` checks each record in the DNS. When the proof of ownership, both DKIM keys, the SPF and the MX are in place, the domain is verified.

Then `create_inbox` creates inboxes on this domain. A first message to a recipient leaves from them. The warm-up applies to each inbox: 5 e-mails a day the first week, then 10, 15 and 20.

Good to know before you start:

- **A subdomain is enough**, for example `agents.example.com`. It is the right choice if your domain already receives mail elsewhere: the MX record makes all the registered domain's mail arrive in your Escouade Mail inboxes.
- **A verified domain belongs to one space only.** Registering a domain does not reserve it: it goes to the first space that publishes its proof of ownership. A domain whose ownership another space has already proven is refused: `domain_taken`.
- **Five domains at most per space**: beyond that, `domain_limit`.
- **A public mail service** (`gmail.com`…) cannot be registered: `public_mail_domain`.
- **An active plan is required.** Before payment, `add_domain` is refused with the code `payment_required`.
- The space must be verified, and the key must carry `manage_inboxes`.

## The DNS records

`add_domain` returns six records. Five are required; DMARC is recommended.

| Role | Type | Name | Value | Required |
|---|---|---|---|---|
| Proof of ownership | TXT | `_subagent.example.com` | `subagent-verification=…` | yes |
| DKIM (RSA) | TXT | `sa-rsa-20261013._domainkey.example.com` | `v=DKIM1; k=rsa; p=…` | yes |
| DKIM (Ed25519) | TXT | `sa-ed-20261013._domainkey.example.com` | `v=DKIM1; k=ed25519; p=…` | yes |
| SPF | TXT | `example.com` | `v=spf1 include:spf.subagent.fr -all` | yes |
| MX | MX | `example.com` | `10 mx1.subagent.fr.` | yes |
| DMARC | TXT | `_dmarc.example.com` | `v=DMARC1; p=none` | no |

The exact values, with your proof token and your keys, are those `add_domain` returns: copy them as they are. The DKIM key names carry the registration date.

- **SPF**: a domain has only one SPF record. If it already has one, add the `include` given by `add_domain` to it instead of creating a second one.
- **DKIM**: the RSA key is long. If your DNS host limits a string to 255 characters, it splits it into several strings of the same record.
- **DMARC**: start with `p=none`, then tighten (`p=quarantine`, then `p=reject`) once your sends are aligned.

## `add_domain`

Registers a domain and returns its DNS records. Nothing changes until `verify_domain` has found them. Called again for a domain the space has already registered, it gives its records again. Permission: `manage_inboxes`. The space must be verified, and have an active plan.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `domain` | text | yes | The domain name alone, for example `example.com` or `agents.example.com`. No `http://`, no `@`. |

```text
Domaine exemple.fr enregistré (dom_4a7c1e9b2f6d48a3b5c0e8d1f2a6b9c7), en attente de vérification. Publiez ces enregistrements chez l’hébergeur DNS du domaine, puis appelez verify_domain. Tant qu’il n’est pas vérifié, aucune boîte ne s’y crée.

1. Preuve de propriété — TXT
   Nom    : _subagent.exemple.fr
   Valeur : subagent-verification=…
2. DKIM (RSA) — TXT
   Nom    : sa-rsa-20261013._domainkey.exemple.fr
   Valeur : v=DKIM1; k=rsa; p=…
   Note   : Valeur longue : si votre hébergeur DNS limite une chaîne à 255 caractères, il la découpe en plusieurs chaînes d’un même enregistrement.
3. DKIM (Ed25519) — TXT
   Nom    : sa-ed-20261013._domainkey.exemple.fr
   Valeur : v=DKIM1; k=ed25519; p=…
4. SPF — TXT
   Nom    : exemple.fr
   Valeur : v=spf1 include:spf.subagent.fr -all
   Note   : Un domaine n’a qu’un enregistrement SPF : s’il en a déjà un, ajoutez-y include:spf.subagent.fr au lieu d’en créer un second.
5. MX — MX
   Nom    : exemple.fr
   Valeur : 10 mx1.subagent.fr.
   Note   : Tout le courrier de exemple.fr arrive alors dans vos boîtes Subagent. Si ce domaine reçoit déjà du courrier ailleurs, enregistrez plutôt un sous-domaine, par exemple agents.exemple.fr.
6. DMARC (conseillé) — TXT
   Nom    : _dmarc.exemple.fr
   Valeur : v=DMARC1; p=none
   Note   : Conseillé, non exigé. À durcir ensuite (p=quarantine, puis p=reject) une fois vos envois alignés ; ajoutez rua=mailto:… vers une adresse que vous relevez pour recevoir les rapports.
```

## `verify_domain`

Checks the domain's records in the DNS, and returns the state of each one: found, missing, or a different value, with the value seen. A DNS change sometimes takes a few minutes to show: fix it, then call again. Permission: `manage_inboxes`. The space must be verified.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `domain` | text | yes | The domain to check (see `list_domains`). |

As long as a required record is missing, the response says which one:

```text
Domaine exemple.fr pas encore vérifié : 4 enregistrements exigés sur 5 sont en place ; à corriger : SPF (valeur différente). Un changement de DNS met parfois quelques minutes à se voir : corrigez, puis rappelez verify_domain.
```

When the proof of ownership, both DKIM keys, the SPF and the MX are in place, the response says the domain is verified and that inboxes can be created on it. It also points out a missing DMARC: it is recommended, not required.

Each response is followed by the list of records, each with its state. If DNS resolution itself fails, nothing is checked and the domain's state does not change: code `dns_unavailable`.

## `list_domains`

Lists the domains the space has registered, with their state, their DNS records and what was seen at the last check. It takes no parameters. Permission: `manage_inboxes` or `read`.

## `remove_domain`

Removes a domain from the space: no more inboxes are created on it, and the mail server stops receiving its mail. Refused while one of the space's inboxes lives on this domain: delete them first (`domain_in_use`). Do this before pointing the domain's MX elsewhere. Then remember to remove its records from your DNS. Irreversible: registering it again will give new DKIM keys. Permission: `manage_inboxes`. The space must be verified.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `domain` | text | yes | The domain to remove (see `list_domains`). |
| `confirm` | boolean | yes | Must be `true`: removal is irreversible. |

## A domain's quality

Over 7 or 30 days, `domain_quality` says what a domain's inboxes sent and what became of it: sends accepted, confirmed deliveries, bounces, complaints, their rates, the state of the DNS, and each inbox's quotas and protections. It is not a reputation score: these are Escouade Mail's sends, and history imported from another tool is excluded. `inspect_domain` looks, before any registration, at where the domain already receives its mail (MX) and what its SPF says, and suggests a sending subdomain when the domain receives elsewhere.

## `inspect_domain`

Checks the current MX and SPF before registration. Access: `manage_inboxes`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `domain` | text | yes | Domain name, without an e-mail address or a URL. |

[Full reference](https://escouade.io/en/mail/docs/reference/inspect_domain.md)

## `domain_quality`

Shows in Domains the sending quality of a domain belonging to this space over 7 or 30 days: known DNS configuration, Escouade Mail sends, confirmed deliveries, bounces, complaints, quotas and protections of its reachable inboxes. Access: `read` or `manage_inboxes`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `domain` | text | yes | A domain registered in this space (list_domains). |
| `days` | integer | no | Period in Paris calendar days, today included. |

[Full reference](https://escouade.io/en/mail/docs/reference/domain_quality.md)

## A domain's states

| State | Meaning |
|---|---|
| `pending` | Waiting for verification: DNS to publish. No inbox is created on it. |
| `verified` | Verified: inboxes are created on it, and they send. |
| `suspended` | Suspended: a required record has disappeared from the DNS. Its inboxes no longer send. |

A verified domain is checked again every day. If a required record has disappeared, the domain is suspended: its messages wait, and any new send is refused with the code `domain_suspended`. Put the records back: a suspended domain is checked again every hour and is reinstated on its own, or straight away through `verify_domain`.

## The fields of a domain

| Field | Content |
|---|---|
| `id` | The domain identifier, `dom_…`. |
| `domain` | The domain name. |
| `status`, `status_reason` | The state, and the reason for a suspension. |
| `created_at`, `verified_at`, `last_checked_at` | The dates, in ISO 8601. |
| `records` | The records: `role` (`ownership`, `dkim`, `spf`, `mx`, `dmarc`), `label`, `type` (`TXT` or `MX`), `name`, `value`, `required`, `note`, and at the last check `state` (`found`, `missing`, `different`) and `seen`. |