Sequences API

The Sequences API allows you to add and remove subscribers within sequences programmatically, as well as list current subscribers in a sequence.

This API endpoint is not for modifying or creating sequences themselves. This must be done within Broadcast’s user interface.

Required Permissions

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

  • List and read subscribers in sequences (Read)
  • Add or remove subscribers from sequences (Write)

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

Endpoints

Important: For the following endpoints, you will need the id of the sequence. You can find this in the URL of the sequence in the user interface.

For example, if your sequence URL is https://broadcast.example.com/sequences/6, then the id would be 6.

List Subscribers in a Sequence

GET /api/v1/sequences/:id/list_subscribers.json?page=1

Returns a paginated list of subscribers in the specified sequence.

Parameters

  • id (required): The ID of the sequence in the URL
  • page: The page number to return (default is 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

Note that this endpoint will try and add an existing subscriber to the sequence based on the email address.

If the subscriber email does not exist in the system, the subscriber will be created along with adding them to the sequence.

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

Adds a subscriber to the specified sequence.

Parameters

  • id (required): The ID of the sequence in the URL

And the following parameters under the “subscriber” key:

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

Request

curl -X POST 'https://your-broadcast-domain.com/api/v1/sequences/123/add_subscriber.json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "subscriber": {
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe"
    }
  }'

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

  • id (required): The ID of the sequence in the URL

And the following parameters under the “subscriber” key:

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

Request

curl -X DELETE 'https://your-broadcast-domain.com/api/v1/sequences/123/remove_subscriber' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "subscriber": {
      "email": "[email protected]"
    }
  }'

Response

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