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

# Contacts and audiences

> A contact is one record per address: its name, its fields, its tags, and whatever blocks it. An audience is a list of contacts, the one a campaign goes to. Your agent keeps them up to date; nothing here sends an e-mail.

## The directory

Every address has a global record in the space: a name, free fields (`fields`, text values such as `prenom` or `societe`) and tags (`labels`). `list_contacts` searches the directory (address, name, fields), filters by tag, by audience or by subscription state. `get_contact` reads a record, its audiences and its effective block.

The subscription state says what the space knows: `subscribed` (no known block, which is not proof of consent), `unsubscribed` (unsubscribed) or `blocked` (another effective block: bounce, complaint, manual block). A blocked address receives nothing more, from any inbox (see [Unsubscribes](https://escouade.io/en/mail/docs/desinscription.md)).

The directory and audiences need a key that reaches every inbox of the space: a key limited to some inboxes is refused (`contact_scope`, `audience_scope`).

## Audiences

`save_audience` creates an audience or renames it; `import_contacts` adds or updates 1 to 500 contacts in it at a time (a batch containing an error is refused as a whole); `remove_audience_contact` removes an address from it. An address appears only once per audience.

An audience keeps its own copy of each contact's fields: changing the global record (`save_contact`) rewrites neither the audiences nor the campaigns already scheduled. `set_contact_audiences` chooses all of a record's audiences at once: a new membership copies the global record, the ones that remain keep their fields.

Removing a contact from an audience does not touch a campaign already scheduled. To stop every send to an address, block it (`add_suppression`).

## The tools

### `list_contacts`

The space's global directory, independent of audiences: search, tags, membership, and unsubscribe or other effective block. Access: `read`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | text | no | Search in the address, the name and the fields. |
| `label` | text | no | Exact tag. |
| `audience_id` | `aud_…` identifier | no | Limit to one of the space's audiences. |
| `subscription` | text | no | subscribed: no known block (not proof of consent). unsubscribed: unsubscribed. blocked: another effective block. |
| `offset` | integer | no | The rank of the first item returned, from 0 to 100,000: the `next_offset` value from the previous call. |
| `limit` | integer | no | The number of records returned, from 1 to 200. 100 by default. |

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

### `get_contact`

Global record, audiences and effective block. Access: `read`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `email` | text | yes | Exact address of the contact. |

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

### `save_contact`

Creates or updates the global record: properties left out are kept. Access: `send`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `email` | text | yes | Unique address: creates the record if it does not exist. |
| `name` | text | no | Name. Absent: kept; empty: erased. |
| `fields` | object | no | Replaces the global fields if given; fields specific to audiences stay unchanged. |
| `labels` | list | no | Replaces the global tags if given. |

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

### `set_contact_audiences`

Replaces all of the contact's memberships with audience_ids (empty: none). Access: `send`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `email` | text | yes | Exact address of the existing record. |
| `audience_ids` | list | yes | All of the record's audiences, 200 at most. An empty list removes it from all of them. |

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

### `list_audiences`

The space's audiences, their origin and number of contacts. Access: `read`.

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

### `get_audience`

An audience's contacts, 200 per page; continue from next_offset. Access: `read`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `audience_id` | `aud_…` identifier | yes | Audience. |
| `offset` | integer | no | The rank of the first item returned, from 0 to 100,000: the `next_offset` value from the previous call. |

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

### `save_audience`

Creates an audience, or renames the one given by audience_id. Access: `send`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `audience_id` | `aud_…` identifier | no | Audience to rename, optional. |
| `name` | text | yes | Name of the audience. |

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

### `import_contacts`

Adds or updates 1 to 500 contacts. Access: `send`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `audience_id` | `aud_…` identifier | yes | Target audience. |
| `contacts` | list | yes | From 1 to 500 contacts: `email` (required), `name`, `fields` (text values) and `labels`. An invalid batch is refused as a whole. |

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

### `remove_audience_contact`

Removes the address from an audience. Access: `send`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `audience_id` | `aud_…` identifier | yes | Audience. |
| `email` | text | yes | Exact address. |

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