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.

Formulario de alta público

Cada lista puede tener un formulario público donde la gente se suscribe sola. Es lo que pones como destino de un anuncio, o lo que pegas en tu sitio.

Ver el estado

GET /v1/bulk/lists/{id}/signup-form

Activar o reconfigurar

PUT /v1/bulk/lists/{id}/signup-form

Body opcional:

Campo	Tipo	Descripción
tags	array	Etiquetas que se le ponen a quien entre por aquí. Útil para saber de qué anuncio vino cada quien.
redirect_url	string	A dónde mandarlo tras suscribirse. Vacío = nuestra página de gracias.
regenerate	boolean	Cambia el token del formulario.

La respuesta trae:

Campo	Descripción
activo	Si el formulario está recibiendo altas.
url	Página hospedada por nosotros, lista para usar.
snippet	HTML listo para pegar en tu propio sitio.
token	El identificador público del formulario.
doble_optin	Si esta lista exige confirmación.

Apagarlo

DELETE /v1/bulk/lists/{id}/signup-form

`regenerate` revoca lo que ya publicaste

regenerate: true cambia el token, así que el formulario que ya tengas pegado en un sitio deja de funcionar y hay que volver a publicar el nuevo. Se usa cuando el token se filtró o alguien está abusando de él, no de rutina.

Un formulario abierto es distinto a un import

Cualquiera puede escribir el correo de otra persona en un formulario público. Si el tuyo está en una página abierta, el doble opt-in de abajo es lo que prueba que el dueño de esa dirección realmente quiso suscribirse.

Un alta por este formulario sí dispara las secuencias con list_join, a diferencia de un import masivo. Ver la guía Leads de anuncios — desde el panel.

Doble opt-in (confirmación de suscripción)

Puedes exigir que los contactos confirmen su suscripción antes de recibir campañas de una lista — protege tu reputación de envío y es el estándar (estilo Mailchimp) para dejar constancia de consentimiento explícito.

Configurar doble opt-in

PUT /v1/bulk/lists/{id}/confirmation

Body:

{
  "require_confirmation": true,
  "confirm_from_email": "noreply@tuempresa.com",
  "confirm_from_name": "Tu Empresa",
  "confirm_subject": "Confirma tu suscripción",
  "confirm_intro": "Gracias por suscribirte. Confirma tu email para empezar a recibir nuestros correos."
}

confirm_from_email debe pertenecer a un dominio verificado de tu cuenta (misma regla que el from de una campaña). Al activar require_confirmation en una lista con miembros existentes, esos miembros quedan confirmados automáticamente (no se les pide confirmar retroactivamente) — solo los contactos que agregues después pasan por el flujo de confirmación.

Mientras la lista exige confirmación, cada contacto nuevo agregado vía POST /v1/bulk/lists/{id}/contacts recibe automáticamente un correo con un enlace de confirmación de un clic (endpoint público GET /confirm-subscription?token=...). Un contacto que no ha confirmado queda en estado pendiente y se excluye de los envíos de campañas a esa lista hasta que confirme.

---

Reenviar confirmación a un contacto pendiente

POST /v1/bulk/lists/{id}/contacts/{email}/resend-confirmation

Reenvía el correo de confirmación. Devuelve 400 si la lista no exige confirmación, y 429 si ya reenviaste hace menos de 5 minutos (protección anti mail-bomb).

{ "resent": true }

Consejo

El evento de webhook contact.confirmed se dispara cuando un contacto confirma su suscripción — úsalo para sincronizar el estado en tus propios sistemas. Ver webhooks.

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.