Sequences API

The Sequences API provides full CRUD (Create, Read, Update, Delete) operations for managing automated email sequences and their steps. You can create sequences, add steps (emails, delays, conditions), and manage subscriber enrollment programmatically.

Required Permissions

All endpoints require authentication via an API token with appropriate permissions:

• Read Permission: Required for GET endpoints (list, show sequences and steps)
• Write Permission: Required for POST, PATCH, DELETE endpoints (create, update, delete sequences and steps)
• Subscribers Read: Required for listing subscribers in a sequence
• Subscribers Write: Required for adding/removing subscribers from sequences

Sequence Object

The sequence object contains the following fields:

List Sequences

GET /api/v1/sequences

Retrieve a list of all sequences for the authenticated broadcast channel.

Query Parameters

• limit (optional): Maximum number of sequences to return, from 1 to 1000
• offset (optional): Number of sequences to skip, 0 or more

A limit or offset outside those ranges, or that is not a whole number, returns 422 Unprocessable Entity.

Request

curl -X GET \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  http://your-domain.com/api/v1/sequences

Response

{
  "data": [
    {
      "id": 1,
      "label": "Welcome Series",
      "active": true,
      "track_opens": true,
      "track_clicks": true,
      "use_any_email_server": true,
      "email_server_ids": [],
      "init_segment_id": null,
      "init_tag": null,
      "parent_sequence_id": null,
      "subscribers_count": 150,
      "created_at": "2024-01-01T12:00:00Z",
      "updated_at": "2024-01-01T12:00:00Z"
    }
  ],
  "total": 1
}

Get Sequence

GET /api/v1/sequences/:id

Retrieve details of a specific sequence.

Query Parameters

• include_steps (optional): Set to true to include all steps in the response

Request

curl -X GET \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  "http://your-domain.com/api/v1/sequences/123?include_steps=true"

Response

{
  "id": 123,
  "label": "Welcome Series",
  "active": true,
  "track_opens": true,
  "track_clicks": true,
  "use_any_email_server": true,
  "email_server_ids": [],
  "init_segment_id": null,
  "init_tag": "new-subscriber",
  "parent_sequence_id": null,
  "subscribers_count": 150,
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T12:00:00Z",
  "steps": [
    {
      "id": 1,
      "action": "entry_point",
      "label": "Entry Point",
      "parent_id": null
    },
    {
      "id": 2,
      "action": "send_email",
      "label": "Welcome Email",
      "parent_id": 1,
      "subject": "Welcome to our service!"
    }
  ]
}

Create Sequence

POST /api/v1/sequences

Create a new sequence. An entry point step is automatically created with the sequence.

Parameters

• label (required): Name of the sequence
• active (optional): Whether the sequence is active (default: false)
• track_opens (optional): Enable open tracking. Left out, it uses the channel default (tracking.track_opens in the Channel Settings API), which is false unless you changed it. An open condition step turns it on.
• track_clicks (optional): Enable click tracking. Left out, it uses the channel default tracking.track_clicks (false unless you changed it). A click condition step turns it on.
• use_any_email_server (optional): Use any available email server (default: true)
• email_server_ids (optional): Array of specific email server IDs
• init_segment_id (optional): Segment ID for automatic enrollment
• init_tag (optional): Tag that triggers automatic enrollment

Request

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sequence": {
      "label": "Onboarding Series",
      "active": true,
      "track_opens": true,
      "track_clicks": true,
      "init_tag": "new-signup"
    }
  }' \
  http://your-domain.com/api/v1/sequences

Response

{
  "id": 123
}

Update Sequence

PATCH /api/v1/sequences/:id

Update an existing sequence.

Request

curl -X PATCH \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sequence": {
      "label": "Updated Onboarding Series",
      "active": false
    }
  }' \
  http://your-domain.com/api/v1/sequences/123

Response

Returns the updated sequence object.

Delete Sequence

DELETE /api/v1/sequences/:id

Delete a sequence and all its steps.

Request

curl -X DELETE \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  http://your-domain.com/api/v1/sequences/123

Response

{
  "message": "Sequence deleted successfully"
}

Sequence Steps API

Manage individual steps within a sequence. Steps define the actions taken as subscribers progress through the sequence.

Step Object

Supported Step Actions

Condition Settings

For condition steps, use one of these condition settings:

• any_email_opened - Subscriber opened any email in this sequence
• previous_email_opened - Subscriber opened the previous email
• any_email_clicked - Subscriber clicked any link in this sequence
• previous_email_clicked - Subscriber clicked a link in the previous email

List Steps

GET /api/v1/sequences/:sequence_id/steps

Request

curl -X GET \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  http://your-domain.com/api/v1/sequences/123/steps

Response

{
  "data": [
    {
      "id": 1,
      "action": "entry_point",
      "label": "Entry Point",
      "parent_id": null,
      "true_branch": true,
      "has_true_branch": true,
      "has_false_branch": false,
      "ready": true,
      "created_at": "2024-01-01T12:00:00Z",
      "updated_at": "2024-01-01T12:00:00Z"
    },
    {
      "id": 2,
      "action": "send_email",
      "label": "Welcome Email",
      "parent_id": 1,
      "subject": "Welcome!",
      "body": "Hello {{subscriber.first_name}}...",
      "ready": true
    }
  ],
  "total": 2
}

Get Step

GET /api/v1/sequences/:sequence_id/steps/:id

Request

curl -X GET \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  http://your-domain.com/api/v1/sequences/123/steps/456

Create Step

POST /api/v1/sequences/:sequence_id/steps

Create a new step in the sequence. The step will be added as a child of the specified parent.

Common Parameters

• action (required): The type of step action
• label (required): Display name for the step
• parent_id (required): ID of the parent step to attach to

Additional Parameters for send_email Action

• subject: Email subject line
• preheader: Email preview text
• body: Email body content
• html_body: Whether body is HTML (default: false)
• html_body_add_footer: Whether the channel footer is appended to an HTML email. An email with its own unsubscribe link (a footer block that shows the link, or a {{ unsubscribe_url }} link that every subscriber sees) never gets the channel footer on top, whatever this value (2.46.0 or later). Without an own link, rich text and block emails always get the channel footer, and HTML emails follow this value. A step that uses a template_id follows the template’s setting instead, and that is the value the API returns. A value that disagrees with the document or the template is replaced, and the response carries a parameter_overridden warning (see API Response Warnings).
• include_unsubscribe_link: Whether the email carries Broadcast’s unsubscribe link (default: true). When false, the email gets no channel footer and no List-Unsubscribe header, {{ unsubscribe_url }} renders blank, a footer block hides its unsubscribe link, and a hand-written link to {{ unsubscribe_url }} is removed with its text. A step that uses a template_id follows this value too. Accepted by the API in 2.46.0 or later.
• template_id: Use an existing template instead of custom content
• content_type: Content type (“plain”, “html”, or “blocks”)
• blocks_json: JSON for drag-and-drop email builder blocks

Send Email Step

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sequence_step": {
      "action": "send_email",
      "label": "Welcome Email",
      "parent_id": 1,
      "subject": "Welcome to our service!",
      "preheader": "Thanks for joining",
      "body": "Hello {{ subscriber.first_name }}, welcome aboard!",
      "html_body": false,
      "html_body_add_footer": true,
      "include_unsubscribe_link": true
    }
  }' \
  http://your-domain.com/api/v1/sequences/123/steps

Delay Step

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sequence_step": {
      "action": "delay",
      "label": "Wait 1 day",
      "parent_id": 2,
      "delay": 86400
    }
  }' \
  http://your-domain.com/api/v1/sequences/123/steps

Delay Until Time Step

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sequence_step": {
      "action": "delay_until_time",
      "label": "Send at 9 AM",
      "parent_id": 3,
      "delay_until_time": "09:00:00",
      "delay_until_timezone": "America/New_York"
    }
  }' \
  http://your-domain.com/api/v1/sequences/123/steps

Condition Step

Creating a condition step automatically creates true/false branch steps:

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sequence_step": {
      "action": "condition",
      "label": "Check if opened email",
      "parent_id": 4,
      "condition_setting": "previous_email_opened"
    }
  }' \
  http://your-domain.com/api/v1/sequences/123/steps

Move to Sequence Step

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sequence_step": {
      "action": "move_to_sequence",
      "label": "Move to Sales Sequence",
      "parent_id": 5,
      "target_sequence_id": 10
    }
  }' \
  http://your-domain.com/api/v1/sequences/123/steps

Add/Remove Tag Step

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sequence_step": {
      "action": "add_tag_to_subscriber",
      "label": "Add engaged tag",
      "parent_id": 6,
      "taggify_list": "engaged,active"
    }
  }' \
  http://your-domain.com/api/v1/sequences/123/steps

Response

{
  "id": 456
}

Update Step

PATCH /api/v1/sequences/:sequence_id/steps/:id

Update an existing step. The action type cannot be changed after creation. The parameters are the same as for Create Step, include_unsubscribe_link included.

Request

curl -X PATCH \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sequence_step": {
      "label": "Updated Welcome Email",
      "subject": "Welcome to our amazing service!"
    }
  }' \
  http://your-domain.com/api/v1/sequences/123/steps/456

Response

Returns the updated step object.

Delete Step

DELETE /api/v1/sequences/:sequence_id/steps/:id

Delete a step. Entry point steps cannot be deleted. When a parent step is deleted, its children are reassigned to the grandparent.

Request

curl -X DELETE \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  http://your-domain.com/api/v1/sequences/123/steps/456

Response

{
  "message": "Step deleted successfully"
}

Move Step

POST /api/v1/sequences/:sequence_id/steps/:id/move

Move a step to be under a different parent step.

Movable Step Types

• send_email
• delay
• delay_until_time
• move_to_sequence
• deactivate_subscriber
• add_tag_to_subscriber
• remove_tag_from_subscriber
• make_http_request

Non-Movable Step Types

• entry_point
• condition
• condition_branch

Request

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "under_id": 5
  }' \
  http://your-domain.com/api/v1/sequences/123/steps/456/move

Response

Returns the updated step object with new parent_id.

Subscriber Enrollment

Manage subscriber enrollment in sequences.

Subscriber Sequence Object

List Subscribers in a Sequence

GET /api/v1/sequences/:id/list_subscribers

Returns a paginated list of subscribers in the specified sequence. Redacted (GDPR-erased) subscribers are left out.

Query Parameters

• page (optional): The page number to return (default is 1)

Request

curl -X GET \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  "http://your-domain.com/api/v1/sequences/123/list_subscribers?page=1"

Response

{
  "subscriber_sequences": [
    {
      "id": "123",
      "status": "active",
      "started_at": "2024-03-20T10:00:00Z",
      "completed_at": null,
      "next_trigger_at": "2024-03-21T10:00:00Z",
      "subscriber": {
        "id": "456",
        "email": "user@example.com"
      }
    }
  ],
  "pagination": {
    "prev": null,
    "next": 2,
    "count": 95,
    "pages": 10,
    "page": 1
  }
}

Add Subscriber to Sequence

POST /api/v1/sequences/:id/add_subscriber

Adds a subscriber to the specified sequence. If the subscriber email does not exist in the system, the subscriber will be created.

Parameters

• email (required): The email address of the subscriber
• first_name (optional): The first name of the subscriber
• last_name (optional): The last name of the subscriber

Request

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber": {
      "email": "user@example.com",
      "first_name": "John",
      "last_name": "Doe"
    }
  }' \
  http://your-domain.com/api/v1/sequences/123/add_subscriber

Response

Returns 201 Created on success or 422 Unprocessable Entity if the request fails. A redacted (GDPR-erased) subscriber cannot be enrolled and returns 404 Not Found.

Remove Subscriber from Sequence

DELETE /api/v1/sequences/:id/remove_subscriber

Removes a subscriber from the specified sequence.

Parameters

• email (required): The email address of the subscriber

Request

curl -X DELETE \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber": {
      "email": "user@example.com"
    }
  }' \
  http://your-domain.com/api/v1/sequences/123/remove_subscriber

Response

Returns 200 OK on success or 422 Unprocessable Entity if the request fails.

Error Responses

401 Unauthorized

{
  "error": "Unauthorized"
}

404 Not Found

{
  "error": "Sequence not found"
}

{
  "error": "Step not found"
}

422 Unprocessable Entity

{
  "error": "Label can't be blank"
}

{
  "error": "Cannot delete entry_point step"
}

{
  "error": "Cannot move entry_point step"
}