Lister les contacts

GET /api/v1/contacts Les contacts d'une liste, paginés. listId est obligatoire : une lecture porte toujours sur une seule liste, il n'existe pas de liste de contacts à l'échelle de l'organisation. Une requête sans ce paramètre répond 400. Récupérez vos identifiants de listes avec GET /api/v1/lists — voir Découverte. tagId attend l'identifiant d'un tag, pas son nom : appelez d'abord GET /api/v1/tags et prenez l'id du tag dont le name vous intéresse.
L'organisation n'est jamais un paramètre. Elle vient de la clé. Un organizationId passé dans la requête est ignoré — vous ne pouvez jamais lire que votre propre audience. Un listId appartenant à une autre organisation répond 404, pas une page vide.
Chaque contact de la réponse porte exactement ces champs : id, email, firstName, lastName, status, listId, list, tags et ses dates createdAt / updatedAt. Rien d'autre — en particulier, le jeton de désabonnement d'un contact n'est jamais exposé par cette API.

Autorisation

Rôle dans l'organisationCet endpoint
OWNERAutorisé
ADMINAutorisé
MEMBERAutorisé
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ètreTypeDescription
listIdstringListe à lire. Les contacts portent toujours sur une liste.
statusstringpending, subscribed, unsubscribed, bounced, complained
tagIdstringUniquement les contacts portant ce tag — un identifiant de tag, pas un nom
searchstringCherche dans l'e-mail, le prénom ou le nom
pagenumberVaut 1 par défaut
limitnumberVaut 20 par défaut, plafonné à 100

Exemple

bash
curl -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/contacts?listId=$LIST_ID&status=subscribed&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

ChampTypeDescription
successbooleanIndique si l'opération a réussi
data[].idstringIdentifiant unique du contact
data[].emailstringSon adresse — unique au sein de sa liste
data[].firstNamestringnull
data[].lastNamestringnull
data[].statusstringpending, subscribed, unsubscribed, bounced, complained
data[].listIdstringLa liste à laquelle il appartient
data[].listobject{id, name} de cette liste
data[].tagsarray{id, name} de chaque tag porté
data[].createdAtstringDate de création ISO
data[].updatedAtstringDate ISO de la dernière modification
paginationobject{total, page, limit, totalPages}

Exemple de réponse

json
{
  "success": true,
  "data": [
    {
      "id": "4d19c0a2",
      "email": "ada@example.com",
      "firstName": "Ada",
      "lastName": "Lovelace",
      "status": "subscribed",
      "listId": "0b7c51e8",
      "list": {
        "id": "0b7c51e8",
        "name": "Newsletter"
      },
      "tags": [
        {
          "id": "7c2ef4b1",
          "name": "vip"
        }
      ],
      "createdAt": "2026-08-23T10:22:05.000Z",
      "updatedAt": "2026-08-23T10:22:05.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

Voir aussi