Lister les listes

GET /api/v1/lists Les listes de l'organisation, paginées, chacune avec le nombre de contacts qu'elle contient. C'est là qu'un agent commence : presque tout le reste — ajouter un contact, importer un lot, créer une campagne — demande un listId, et c'est le seul moyen d'en trouver un que vous n'avez pas créé vous-même. Chaque liste porte id, name, contactCount et ses dates createdAt / updatedAt. Les listes supprimées n'apparaissent jamais ici. Une liste que vous avez supprimée dans l'interface disparaît de cette collection, et ses contacts avec elle — les campagnes déjà envoyées à cette liste conservent leur rapport et leurs destinataires.

Autorisation

Rôle dans l'organisation	Cet endpoint
`OWNER`	Autorisé
`ADMIN`	Autorisé
`MEMBER`	Autorisé

Une clé porte le rôle que son créateur détient dans cette organisation — jamais un rôle sur AgentsMail lui-même. Voir Clés d'API.

Paramètres de requête

Paramètre	Type	Description
`search`	string	Cherche dans le nom de la liste
`page`	number	Vaut `1` par défaut
`limit`	number	Vaut `20` par défaut, plafonné à `100`

Exemple

bash

curl -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/lists?limit=50"

Réponse

200 OK — l'appel a réussi.
401 Unauthorized — clé absente ou invalide, ou son propriétaire a quitté l'organisation.
429 Too Many Requests — plus de 120 requêtes en une minute pour cette clé.

Champs de la réponse

Champ	Type	Description
`success`	boolean	Indique si l'opération a réussi
`data[].id`	string	Identifiant unique de la liste
`data[].name`	string	Nom de la liste
`data[].contactCount`	number	Contacts qu'elle contient
`data[].createdAt`	string	Date de création ISO
`data[].updatedAt`	string	Date ISO de la dernière modification
`pagination`	object	`{total, page, limit, totalPages}`

Exemple de réponse

json

{
  "success": true,
  "data": [
    {
      "id": "4d19c0a2",
      "name": "Newsletter",
      "contactCount": 128,
      "createdAt": "2026-08-23T10:22:05.000Z",
      "updatedAt": "2026-08-23T10:22:05.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

Remarques

Une liste supprimée est absente de cette collection, et ses contacts ne comptent plus dans votre offre. Rien n'est perdu côté rapports : les campagnes envoyées à cette liste conservent leurs statistiques, et chacun de leurs destinataires reste lisible.