Campañas

Una campaña envía un correo a todos los contactos activos de una lista. El proceso es: crear la campaña (en estado draft) → opcional: probarla → enviar o programar → las analíticas se actualizan en tiempo real conforme avanza el despacho.

Operaciones

Gestión

Listar campañas

GET /v1/bulk/campaigns

Parámetros opcionales: status, limit (default 100), offset, key_id.

Crear campaña

POST /v1/bulk/campaigns

Body requerido:

Campo	Tipo	Descripción
`name`	string	Nombre interno de la campaña.
`template_id`	string	ID de la plantilla que se enviará.
`list_id`	string	ID de la lista de contactos destino.
`from_email`	string	Remitente. Debe ser un dominio verificado.

Body opcional: from_name, reply_to.

Respuesta: 201 con el objeto campaña en status: "draft".

Obtener campaña

GET /v1/bulk/campaigns/{id}

Actualizar campaña

PATCH /v1/bulk/campaigns/{id}

Solo disponible cuando status es draft o scheduled. Campos actualizables: name, template_id, list_id, from_email, from_name, reply_to, scheduled_at.

Envío y control

Enviar o programar

POST /v1/bulk/campaigns/{id}/send

Body opcional: { "scheduled_at": "2026-07-01T09:00:00Z" }. Sin body (o sin scheduled_at) el envío es inmediato. Respuesta: 200.

Enviar correo de prueba

POST /v1/bulk/campaigns/{id}/test

Body requerido: { "to": "yo@miempresa.com" }. Body opcional: { "sample_data": {} }. Renderiza la plantilla con datos de muestra y la envía a la dirección indicada. Respuesta: 200.

Pausar

POST /v1/bulk/campaigns/{id}/pause

Pausa un envío en curso. Respuesta: 200. Devuelve 409 si la campaña no está en sending.

Reanudar

POST /v1/bulk/campaigns/{id}/resume

Reanuda una campaña pausada. Respuesta: 200. Devuelve 409 si la campaña no está en paused.

Cancelar

POST /v1/bulk/campaigns/{id}/cancel

Cancela la campaña. Disponible desde draft, scheduled, sending o paused. Devuelve 409 si ya está en sent o cancelled.

Duplicar

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

Crea un nuevo draft con los mismos parámetros. Respuesta: 201 con el nuevo objeto campaña.

Analíticas

Analytics detalladas

GET /v1/bulk/campaigns/{id}/analytics

Devuelve métricas de engagement: opens (unique, total, rate), clicks (unique, total, rate, ctor), bounces, complaints, unsubs, rates (open/ctr/ctor/bounce/complaint/unsub), top_links[] y timeline[]. Parámetro opcional: format=csv para exportar.

Reporte de entrega

GET /v1/bulk/campaigns/{id}/report

Estadísticas de entrega de la campaña.

Deliverability

GET /v1/bulk/campaigns/{id}/deliverability

Cruza sends + bounces + complaints. Incluye delivery_rate, bounce_rate, complaint_rate y un breakdown por dominio destino.

Rendimiento cross-campaña

GET /v1/bulk/campaigns/performance

Parámetro opcional: key_id. Devuelve un array de objetos con id, name, status, started_at, delivered, opens_unique, clicks_unique, bounced, open_rate, click_rate y bounce_rate.

Tasas agregadas

GET /v1/bulk/analytics/rates

Parámetros opcionales: period (24h | 7d | 30d, default 7d), key_id, format=csv. Devuelve period, granularity, window_start, totals, rates y series[].

Campañas de reconfirmación

Una lista vieja que nunca se poda es la causa número uno de rebotes duros, y seguir escribiéndole a quien nunca abre es lo que hace que tus correos terminen en spam para los que sí te leen.

El ciclo completo son tres pasos:

1. Segmenta a los inactivos. Con una regla de engagement:

{ "field": "engagement", "op": "not_opened", "days": 180 }

Cuenta solo la apertura humana: las precargas automáticas de Apple Mail Privacy Protection no cuentan como abrir, así que este segmento es de gente que de verdad no vio tus correos.

2. Mándales una campaña con {{reconfirm_url}}. Un solo CTA: «sí, sigo queriendo recibir esto». Quien lo aprieta ve una página de confirmación y queda registrado como activo — sale del segmento de inactivos y de la poda.

3. Da de baja a quien no respondió.

GET  /v1/bulk/campaigns/{id}/sunset
POST /v1/bulk/campaigns/{id}/sunset

El GET te dice a cuántos afectaría antes de hacer nada. El POST marca como unsubscribed a quienes no abrieron, no hicieron clic y no reconfirmaron. Respuesta: { "unsubscribed": 4312 }.

Sus correos transaccionales no se ven afectados: darse de baja del marketing no puede dejar a alguien sin su recuperación de contraseña.

Nunca podamos tu lista por nuestra cuenta. La acción es siempre tuya: «no abrió» es una señal débil, y si tu audiencia bloquea el tracking, automatizar esto te borraría una lista sana.

Ciclo de vida

El estado de una campaña sigue este flujo:

draft
  │
  ├─ /test  (envío de prueba, no cambia estado)
  │
  └─ /send ──► sending ──► sent
                 │
                 ├─ /pause ──► paused
                 │               │
                 └───────────────┘ /resume
                 │
                 └─ /cancel ──► cancelled

  /cancel también disponible desde: draft, scheduled, paused

Los estados posibles son: draft, scheduled, sending, sent, paused, cancelled. Una campaña en sent es inmutable — no puede reenviarse.

Ejemplo completo

# 1. Crear la campaña
curl -X POST https://api.mailerdash.com/v1/bulk/campaigns \
  -H "Authorization: Bearer $MAILERDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter Junio 2026",
    "template_id": "bienvenida-fc9674",
    "list_id": "newsletter-q3-2026-abc123",
    "from_email": "noticias@miempresa.com",
    "from_name": "Mi Empresa",
    "reply_to": "contacto@miempresa.com"
  }'

# 2. Enviar correo de prueba a tu inbox
curl -X POST https://api.mailerdash.com/v1/bulk/campaigns/cmp-d894cd3d626d9d11/test \
  -H "Authorization: Bearer $MAILERDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "yo@miempresa.com"}'

# 3. Lanzar el envío masivo
curl -X POST https://api.mailerdash.com/v1/bulk/campaigns/cmp-d894cd3d626d9d11/send \
  -H "Authorization: Bearer $MAILERDASH_API_KEY"

Referencia

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