Sequences (drip)

Una sequence es una automatización drip: defines una serie de emails (steps) con delays entre ellos, luego suscribes contactos. El sistema envía cada step en el momento correcto sin intervención manual. Son ideales para onboarding, nurturing y follow-ups post-conversión.

Conceptos clave

• Sequence — el contenedor. Tiene nombre y status (draft / active / archived). Debe estar en active para que el worker procese los envíos.
• Step — un email dentro de la sequence. Tiene position (orden de ejecución), offset_seconds (delay desde la suscripción o desde el step anterior), y el contenido del email: subject + html / body_text, o bien un template_id. Al menos uno de los dos esquemas de contenido debe estar presente.
• Subscriber — un contacto suscrito a la sequence. Avanza por los steps en el tiempo configurado, y puede estar en estado activo, pausado, completado o cancelado.

Operaciones

Sequences

Listar

GET /v1/bulk/sequences

Crear

POST /v1/bulk/sequences

Body requerido: { "name": "Nombre de la sequence" }. Respuesta: 201 con status: "draft".

Obtener con sus steps

GET /v1/bulk/sequences/{id}

Actualizar

PATCH /v1/bulk/sequences/{id}

Body: { "name"?: string, "status"?: "draft" | "active" | "archived" }.

Eliminar

DELETE /v1/bulk/sequences/{id}

Devuelve 409 si la sequence tiene subscribers activos o pausados.

Steps

Agregar step

POST /v1/bulk/sequences/{id}/steps

Body requerido:

Campo	Tipo	Descripción
position	integer	Orden del step dentro de la sequence (1, 2, 3…).
offset_seconds	integer	Segundos de espera antes de enviar este step.

Body opcional: subject, html, body_text, from_email, from_name, reply_to, template_id.

Respuesta: 201 con el objeto step. Devuelve 403 si from_email usa un dominio no autorizado en la cuenta.

Actualizar step

PATCH /v1/bulk/sequences/{id}/steps/{step_id}

Acepta los mismos campos opcionales que el POST. Devuelve 403 si from_email usa un dominio no autorizado.

Eliminar step

DELETE /v1/bulk/sequences/{id}/steps/{step_id}

Respuesta: 204.

Subscribers

Listar subscribers

GET /v1/bulk/sequences/{id}/subscribers

Suscribir contacto

POST /v1/bulk/sequences/{id}/subscribers

La operación es idempotente: si el contacto ya tiene una suscripción activa o pausada, devuelve 200 sin crear un duplicado.

Body requerido: { "email": "contacto@example.com" }.
Body opcional: { "started_at"?: string (ISO 8601), "variables"?: object }.

Respuesta: 201 (nueva suscripción) o 200 (ya existía activa/pausada). Devuelve 409 si la suscripción existe en estado terminal (completed o cancelled).

Ver estado de un subscriber

GET /v1/bulk/sequences/{id}/subscribers/{email}

Cancelar suscripción

DELETE /v1/bulk/sequences/{id}/subscribers/{email}

Respuesta: 200.

Pausar

POST /v1/bulk/sequences/{id}/subscribers/{email}/pause

Respuesta: 200. Los steps pendientes se retienen hasta que se reanude.

Reanudar

POST /v1/bulk/sequences/{id}/subscribers/{email}/resume

Respuesta: 200.

Ejemplo: crear una sequence de bienvenida

# 1. Crear la sequence
curl -X POST https://api.mailerdash.com/v1/bulk/sequences \
  -H "Authorization: Bearer $MAILERDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Onboarding - Bienvenida"}'

# Respuesta: { "id": "onboarding-bienvenida-a1b2c3", "status": "draft", ... }

# 2. Agregar primer step (inmediato, offset_seconds=0)
curl -X POST https://api.mailerdash.com/v1/bulk/sequences/onboarding-bienvenida-a1b2c3/steps \
  -H "Authorization: Bearer $MAILERDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "position": 1,
    "offset_seconds": 0,
    "subject": "Bienvenido a {{name}}, aquí empieza todo",
    "from_email": "hola@miempresa.com",
    "template_id": "bienvenida-fc9674"
  }'

# 3. Agregar segundo step (3 días después = 259200 segundos)
curl -X POST https://api.mailerdash.com/v1/bulk/sequences/onboarding-bienvenida-a1b2c3/steps \
  -H "Authorization: Bearer $MAILERDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "position": 2,
    "offset_seconds": 259200,
    "subject": "¿Cómo va todo?",
    "from_email": "hola@miempresa.com",
    "template_id": "followup-fc9675"
  }'

# 4. Activar la sequence
curl -X PATCH https://api.mailerdash.com/v1/bulk/sequences/onboarding-bienvenida-a1b2c3 \
  -H "Authorization: Bearer $MAILERDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

# 5. Suscribir un contacto
curl -X POST https://api.mailerdash.com/v1/bulk/sequences/onboarding-bienvenida-a1b2c3/subscribers \
  -H "Authorization: Bearer $MAILERDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "ana@empresa.com"}'

La suscripción es idempotente

Puedes suscribir el mismo email múltiples veces sin error si ya tiene una suscripción activa o pausada. Solo falla con 409 si la suscripción está en estado terminal (completed o cancelled). Esto hace seguro llamar al endpoint desde lógica de signup sin verificar primero.

La sequence debe estar activa para enviar

En status: "draft" los subscribers se acumulan pero los steps no se procesan. Activa la sequence con PATCH /v1/bulk/sequences/{id} antes de esperar envíos.

Webhooks de sequences

Si tienes webhooks configurados en tu API key, recibirás eventos para cada momento del ciclo de vida de una suscripción:

Evento	Cuándo se dispara
sequence.subscribed	Se suscribe un nuevo contacto.
sequence.step.sent	Un step se envía exitosamente.
sequence.step.failed	Un step falla al enviarse.
sequence.completed	El contacto completó todos los steps.
sequence.cancelled	La suscripción se cancela. Incluye campo reason: unsubscribed, manual, bounced, complained o suppressed.

Referencia

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