Listar las listas

GET /api/v1/lists Las listas de la organización, paginadas, cada una con el número de contactos que contiene. Aquí es donde empieza un agente: casi todo lo demás —añadir un contacto, importar un lote, crear una campaña— necesita un listId, y esta es la única forma de encontrar uno que no creaste tú. Cada lista lleva id, name, contactCount y sus fechas createdAt / updatedAt. Las listas eliminadas nunca aparecen aquí. Una lista que eliminaste en la interfaz desaparece de esta colección, y sus contactos también; las campañas ya enviadas a ella conservan su informe y sus destinatarios.

Autorización

Rol en la organización	Este endpoint
`OWNER`	Permitido
`ADMIN`	Permitido
`MEMBER`	Permitido

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ámetro	Tipo	Descripción
`search`	string	Busca en el nombre de la lista
`page`	number	Por defecto `1`
`limit`	number	Por defecto `20`, con un máximo de `100`

Ejemplo

bash

curl -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/lists?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

Campo	Tipo	Descripción
`success`	boolean	Indica si la operación se realizó correctamente
`data[].id`	string	Identificador único de la lista
`data[].name`	string	Nombre de la lista
`data[].contactCount`	number	Contactos que contiene
`data[].createdAt`	string	Fecha de creación ISO
`data[].updatedAt`	string	Fecha ISO del último cambio
`pagination`	object	`{total, page, limit, totalPages}`

Ejemplo de respuesta

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

Notas

Una lista eliminada no aparece en esta colección, y sus contactos dejan de contar para tu plan. No se pierde nada en los informes: las campañas enviadas a esa lista conservan sus estadísticas, y cada uno de sus destinatarios sigue siendo consultable.