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 URLpage
: 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 subscriberfirst_name
: The first name of the subscriberlast_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.