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

GET /lists

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

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.

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

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

SDK

import { Agentmail } from "./agentmail"

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

Réponse : statut 200.

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

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.