# API listes

Une liste regroupe des contacts, pour une campagne ou un workflow. Un contact entre dans une liste à la création ou à la modification, avec `list_ids` (voir [API contacts](/docs/reference/api-contacts/)).

## GET `/lists`

Renvoie toutes les listes de ton espace. Pas de pagination : elles tiennent toutes dans une réponse.

```bash
curl https://api.mail.hgdc.ch/lists \
  -H "Authorization: Bearer $AGENTMAIL_API_KEY"
```

Réponse : statut `200`. `contacts_count` compte les contacts de la liste.

```json
{
  "object": "list",
  "data": [
    {
      "object": "list",
      "id": "jd7q4v2m8x1r5n9c3b6z0h4w",
      "name": "Clients 2026",
      "contacts_count": 42,
      "created_at": "2026-10-01T09:00:00.000Z"
    }
  ]
}
```

## POST `/lists`

Crée une liste vide.

| Champ  | Type   | Obligatoire | Description                                                                           |
| ------ | ------ | ----------- | ------------------------------------------------------------------------------------- |
| `name` | string | Oui         | Nom de la liste, de 1 à 60 caractères. Les espaces au début et à la fin sont retirés. |

```bash
curl -X POST https://api.mail.hgdc.ch/lists \
  -H "Authorization: Bearer $AGENTMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Clients 2026" }'
```

```ts
import { Agentmail } from "./agentmail"

const mail = new Agentmail()
const list = await mail.lists.create({ name: "Clients 2026" })
```

Réponse : statut `200`.

```json
{
  "object": "list",
  "id": "jd7q4v2m8x1r5n9c3b6z0h4w",
  "name": "Clients 2026"
}
```

Un nom vide ou trop long renvoie `422`, avec `name : 1 à 60 caractères` dans `message`. Le SDK ne réessaie pas cette création : un second appel créerait une seconde liste. Pour réessayer à la main, vérifie d’abord avec `GET /lists`.

## Alias `/segments`

`/segments` accepte les mêmes méthodes, avec les mêmes corps et les mêmes réponses. C’est le nom utilisé par Resend : un code existant fonctionne sans changement.

```bash
curl https://api.mail.hgdc.ch/segments \
  -H "Authorization: Bearer $AGENTMAIL_API_KEY"
```

## Si ça ne marche pas

- **`401 restricted_api_key`** : la clé est de type **Envoi seulement**. Elle ne peut pas lire les listes : utilise une clé à accès complet, réservée au serveur.
- **`422` sur le nom** : il doit faire entre 1 et 60 caractères après suppression des espaces.