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:

Field Description
`id` Unique identifier of the sequence
`label` The name of the sequence
`active` Whether the sequence is active and processing subscribers
`track_opens` Whether open tracking is enabled for emails in this sequence
`track_clicks` Whether click tracking is enabled for emails in this sequence
`use_any_email_server` Whether to use any available email server
`email_server_ids` Array of specific email server IDs to use
`init_segment_id` Segment ID for automatic enrollment trigger
`init_tag` Tag that triggers automatic enrollment
`parent_sequence_id` ID of the sequence this was duplicated from (null if not a duplicate)
`subscribers_count` Number of subscribers currently in the sequence
`created_at` When the sequence was created
`updated_at` When the sequence was last updated

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
  • offset (optional): Number of sequences to skip for pagination

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 (default: true)
  • track_clicks (optional): Enable click tracking (default: true)
  • 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

Field Description
`id` Unique identifier of the step
`action` Type of action (see supported actions below)
`label` Display name for the step
`parent_id` ID of the parent step (null for entry_point)
`true_branch` Whether this step is on the true branch of a condition
`subject` Email subject (for send_email action)
`preheader` Email preheader text (for send_email action)
`body` Email body content (for send_email action)
`html_body` Whether body is HTML (for send_email action)
`html_body_add_footer` Add footer to HTML emails
`delay` Delay in seconds (for delay action)
`delay_until_time` Time to send (for delay_until_time action)
`delay_until_timezone` Timezone for delay_until_time
`condition_setting` Condition type (for condition action)
`target_sequence_id` Target sequence (for move_to_sequence action)
`tags` Tags to add/remove (for tag actions)
`has_true_branch` Whether step has a true branch child
`has_false_branch` Whether step has a false branch child
`ready` Whether the step is ready for processing

Supported Step Actions

Action Description Required Fields
`entry_point` Starting point (auto-created) -
`send_email` Send an email to the subscriber `subject`, `body`
`delay` Wait for specified seconds `delay`
`delay_until_time` Wait until specific time of day `delay_until_time`, `delay_until_timezone`
`condition` Branch based on conditions `condition_setting`
`move_to_sequence` Move subscriber to another sequence `target_sequence_id`
`add_tag_to_subscriber` Add tags to subscriber `taggify_list`
`remove_tag_from_subscriber` Remove tags from subscriber `taggify_list`
`deactivate_subscriber` Deactivate the subscriber -
`make_http_request` Send HTTP webhook -

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.

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
    }
  }' \
  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.

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

Field Description
`id` Unique identifier of the subscriber sequence
`status` Current status of the sequence subscription
`started_at` When the subscriber was added to the sequence
`completed_at` When the subscriber completed or was removed from the sequence
`next_trigger_at` When the next email in the sequence will be sent
`subscriber` Information about the subscriber
`subscriber.id` Unique identifier of the subscriber
`subscriber.email` Email address of the subscriber

List Subscribers in a Sequence

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

Returns a paginated list of subscribers in the specified sequence.

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": "[email protected]"
      }
    }
  ],
  "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": "[email protected]",
      "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.

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": "[email protected]"
    }
  }' \
  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"
}