Crear una lista

POST /api/v1/lists Una lista es el contenedor en el que viven los contactos. Crea una y después aliméntala con los endpoints de contactos. Actualizar y eliminar todavía no están expuestos; leer las listas que ya tienes está en Descubrimiento. La lista siempre se crea en la organización de la clave de API; la respuesta lleva su id, listo para usar en los endpoints de contactos.

Autorización

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

Una clave lleva el rol que su creador tiene en esta organización, nunca un rol sobre AgentsMail en sí. Consulta Claves de API.

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Descripción
`name`	string	sí	De 1 a 100 caracteres

Ejemplo

bash

curl -X POST -H "x-api-key: $AGENTMAIL_API_KEY" -H "content-type: application/json" \
  -d '{"name":"Newsletter"}' \
  "https://www.agentsmail.io/api/v1/lists"

Respuesta

201 Created: el recurso creado.
401 Unauthorized: clave ausente o no válida, o su propietario salió de la organización.
403 Forbidden: el propietario de la clave es member de la organización, no admin.
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

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