Listas

Una lista es un grupo de contactos al que puedes dirigir una campaña. Cada campaña apunta a exactamente una lista, y una lista puede contener cualquier número de contactos activos. Las listas son independientes entre sí: un contacto puede estar en varias listas al mismo tiempo, y removerlo de una lista no lo afecta en las demás ni lo elimina del sistema.

Esquema

Campo	Tipo	Descripción
id	string	Identificador slug de la lista.
name	string	Nombre descriptivo.
key_id	string	API key a la que pertenece.
contact_count	integer	Cantidad de contactos en la lista.
created_at	string	Fecha de creación (ISO 8601).

Operaciones

Listar todas las listas

GET /v1/bulk/lists

Devuelve un array con todas las listas de tu cuenta, incluyendo contact_count de cada una.

---

Crear una lista

POST /v1/bulk/lists

Body:

{ "name": "Newsletter Q3 2026" }

Devuelve 201 con la lista creada, incluyendo su id generado automáticamente.

---

Obtener una lista con sus contactos

GET /v1/bulk/lists/{id}

Devuelve el detalle de la lista más sus contactos paginados.

Parámetros de query:

Parámetro	Descripción
limit	Máximo de contactos a devolver.
offset	Desplazamiento para paginación.
status	Filtra contactos por estado.

---

Renombrar una lista

PATCH /v1/bulk/lists/{id}

Body:

{ "name": "Newsletter Q4 2026" }

---

Eliminar una lista

DELETE /v1/bulk/lists/{id}

Elimina la lista. Devuelve 204 No Content. Si la lista está referenciada por una campaña activa, devuelve 409 Conflict.

---

Agregar contactos a una lista

POST /v1/bulk/lists/{id}/contacts

Body:

{ "emails": ["ana@empresa.com", "pedro@cliente.io"] }

Los emails deben corresponder a contactos ya existentes en tu cuenta. Devuelve 200 con la cantidad de contactos agregados.

---

Remover un contacto de una lista

DELETE /v1/bulk/lists/{id}/contacts/{email}

Quita el contacto de esta lista. Devuelve 204 No Content. El contacto sigue existiendo en el sistema y en cualquier otra lista donde esté incluido.

---

Clonar una lista

POST /v1/bulk/lists/{id}/duplicate

Crea una copia de la lista con todos sus contactos. Útil para crear segmentos derivados sin partir de cero. Devuelve 201 con la nueva lista.

---

Eliminar listas en lote

POST /v1/bulk/lists/delete

Eliminación atómica de múltiples listas. Body:

{ "ids": ["newsletter-q3-abc123", "promo-verano-xyz"] }

Respuesta:

{
  "requested": 2,
  "deleted": 1,
  "not_found": [],
  "forbidden": [],
  "in_use": ["promo-verano-xyz"]
}

Las listas referenciadas por una campaña se reportan en in_use y no se eliminan. Las demás sí se eliminan, incluso en el mismo request.

Ejemplos

Crear una lista y agregar contactos

# 1. Crear la lista
curl -X POST https://api.mailerdash.com/v1/bulk/lists \
  -H "Authorization: Bearer $MAILERDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Newsletter Q3 2026"}'

# 2. Agregar contactos (usa emails ya registrados como contactos)
curl -X POST https://api.mailerdash.com/v1/bulk/lists/newsletter-q3-2026-abc123/contacts \
  -H "Authorization: Bearer $MAILERDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["ana@empresa.com", "pedro@cliente.io"]}'

Consejo

Remover un contacto de una lista no lo elimina del sistema ni lo quita de otras listas. Para eliminarlo permanentemente de tu cuenta, usa DELETE /v1/bulk/contacts/{email}.

Precaución

No puedes eliminar una lista que esté en uso por una campaña activa. Cancela o espera a que la campaña termine antes de eliminar la lista. Si usas el bulk delete, las listas in_use se reportan sin borrarse — el resto sí se elimina.

Referencia

Para el esquema completo de request/response y códigos de error, consulta la referencia de API bulk.