Listar los contactos

GET /api/v1/contacts Los contactos de una lista, paginados. listId es obligatorio: una lectura siempre se limita a una lista, no existe un listado de contactos de toda la organización. Una solicitud sin él responde 400. Obtén los id de tus listas con GET /api/v1/lists; consulta Descubrimiento. tagId recibe el id de una etiqueta, no su nombre: llama primero a GET /api/v1/tags y toma el id de la etiqueta cuyo name buscas.
La organización nunca es un parámetro. Viene de la clave. Un organizationId pasado en la consulta se ignora: solo puedes leer tu propia audiencia. Un listId que pertenece a otra organización responde 404, no una página vacía.
Cada contacto de la respuesta lleva exactamente estos campos: id, email, firstName, lastName, status, listId, list, tags y sus fechas createdAt / updatedAt. Nada más; en particular, esta API nunca expone el token de baja de un contacto.

Autorización

Rol en la organizaciónEste endpoint
OWNERPermitido
ADMINPermitido
MEMBERPermitido
Una clave lleva el rol que su creador tiene en esta organización, nunca un rol sobre AgentsMail en sí. Consulta Claves de API.

Parámetros de consulta

ParámetroTipoDescripción
listIdstringLista que se va a leer. Los contactos siempre se limitan a una lista.
statusstringpending, subscribed, unsubscribed, bounced, complained
tagIdstringSolo los contactos que llevan esta etiqueta: un id de etiqueta, no un nombre
searchstringBusca en el email, el nombre o el apellido
pagenumberPor defecto 1
limitnumberPor defecto 20, con un máximo de 100

Ejemplo

bash
curl -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/contacts?listId=$LIST_ID&status=subscribed&limit=50"

Respuesta

  • 200 OK: la llamada se realizó correctamente.
  • 401 Unauthorized: clave ausente o no válida, o su propietario salió de la organización.
  • 429 Too Many Requests: más de 120 solicitudes en un minuto para esta clave.

Campos de la respuesta

CampoTipoDescripción
successbooleanIndica si la operación se realizó correctamente
data[].idstringIdentificador único del contacto
data[].emailstringSu dirección: única dentro de su lista
data[].firstNamestringnull
data[].lastNamestringnull
data[].statusstringpending, subscribed, unsubscribed, bounced, complained
data[].listIdstringLa lista a la que pertenece
data[].listobject{id, name} de esa lista
data[].tagsarray{id, name} de cada etiqueta que lleva
data[].createdAtstringFecha de creación ISO
data[].updatedAtstringFecha ISO del último cambio
paginationobject{total, page, limit, totalPages}

Ejemplo de respuesta

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

Relacionado