Sequences (drip)

A sequence is a drip automation: you define a series of emails (steps) with delays between them, then subscribe contacts. The system sends each step at the right time without manual intervention. They are ideal for onboarding, nurturing, and post-conversion follow-ups.

Key concepts

• Sequence — the container. Has a name and status (draft / active / archived). Must be in active for the worker to process sends.
• Step — an email within the sequence. Has position (execution order), offset_seconds (delay from subscription or from the previous step), and the email content: subject + html / body_text, or a template_id. At least one of the two content schemes must be present.
• Subscriber — a contact subscribed to the sequence. Advances through the steps over the configured time, and can be in active, paused, completed, or cancelled state.

Operations

Sequences

List

GET /v1/bulk/sequences

Create

POST /v1/bulk/sequences

Required body: { "name": "Sequence name" }. Response: 201 with status: "draft".

Get with its steps

GET /v1/bulk/sequences/{id}

Update

PATCH /v1/bulk/sequences/{id}

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

Delete

DELETE /v1/bulk/sequences/{id}

Returns 409 if the sequence has active or paused subscribers.

Steps

Add step

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

Required body:

Field	Type	Description
position	integer	Order of the step within the sequence (1, 2, 3…).
offset_seconds	integer	Seconds to wait before sending this step.

Optional body: subject, html, body_text, from_email, from_name, reply_to, template_id.

Response: 201 with the step object. Returns 403 if from_email uses a domain not authorized on the account.

Update step

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

Accepts the same optional fields as the POST. Returns 403 if from_email uses an unauthorized domain.

Delete step

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

Response: 204.

Subscribers

List subscribers

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

Subscribe a contact

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

The operation is idempotent: if the contact already has an active or paused subscription, it returns 200 without creating a duplicate.

Required body: { "email": "contacto@example.com" }.
Optional body: { "started_at"?: string (ISO 8601), "variables"?: object }.

Response: 201 (new subscription) or 200 (already existed as active/paused). Returns 409 if the subscription exists in a terminal state (completed or cancelled).

Get subscriber status

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

Cancel subscription

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

Response: 200.

Pause

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

Response: 200. Pending steps are held until resumed.

Resume

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

Response: 200.

Example: create a welcome sequence

# 1. Create the 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"}'

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

# 2. Add the first step (immediate, 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. Add the second step (3 days later = 259200 seconds)
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. Activate the 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. Subscribe a contact
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"}'

Subscription is idempotent

You can subscribe the same email multiple times without error if it already has an active or paused subscription. It only fails with 409 if the subscription is in a terminal state (completed or cancelled). This makes it safe to call the endpoint from signup logic without checking first.

The sequence must be active to send

In status: "draft" subscribers accumulate but steps are not processed. Activate the sequence with PATCH /v1/bulk/sequences/{id} before expecting any sends.

Sequence webhooks

If you have webhooks configured on your API key, you will receive events for each moment in a subscription’s lifecycle:

Event	When it fires
sequence.subscribed	A new contact subscribes.
sequence.step.sent	A step is sent successfully.
sequence.step.failed	A step fails to send.
sequence.completed	The contact completed all steps.
sequence.cancelled	The subscription is cancelled. Includes a reason field: unsubscribed, manual, bounced, complained, or suppressed.

Reference

For the full request/response schema and error codes, see the bulk API reference.