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[].

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.