Subscribers API
The Subscribers API allows you to programmatically manage your subscriber list. It supports comprehensive filtering capabilities to enable efficient querying and external system synchronization.
Required Permissions
All endpoints require authentication via an API token with appropriate permissions:
- List and read subscribers (Read)
- Create and update subscribers (Write)
Common Use Cases
The filtering capabilities are particularly useful for:
- External System Synchronization: Sync unsubscribed users with your CRM by filtering
subscription_status=unsubscribed
- Segment Management: Export specific subscriber segments based on tags, source, or activity status
- Data Cleanup: Identify inactive subscribers or those who haven’t been emailed recently
- Analytics and Reporting: Generate reports for subscribers by date ranges or custom attributes
- Compliance: Efficiently retrieve subscription status for regulatory reporting
Subscriber Object
The subscriber object contains the following fields:
Field | Description |
---|---|
`id` | The ID of the subscriber |
`email` | The email address of the subscriber |
`first_name` | The first name of the subscriber |
`last_name` | The last name of the subscriber |
`ip_address` | The IP address of the subscriber |
`is_active` | Whether the subscriber is active |
`source` | The source of the subscriber |
`subscribed_at` | The date and time the subscriber was subscribed |
`unsubscribed_at` | The date and time the subscriber was unsubscribed |
`last_email_sent_at` | The date and time the subscriber was last sent an email |
`created_at` | The date and time the subscriber was created |
`tags` | An array of tags associated with the subscriber |
`custom_data` | A JSON object, with key-value pairs |
List Subscribers
GET /api/v1/subscribers.json
Parameters
Pagination
page
: The page number to return (default is 1)
Filtering Parameters
The following filtering parameters can be used to filter the subscribers list:
Subscription Status Filtering:
subscriptionstatus
: Filter by subscription statussubscribed
: Subscribers who have not unsubscribed (unsubscribedat is null)unsubscribed
: Subscribers who have unsubscribed (unsubscribedat is not null)active
: Subscribers marked as active (isactive = true)inactive
: Subscribers marked as inactive (is_active = false)
Source Filtering:
source
: Filter by how the subscriber was added (e.g.,website
,api
,import
)
Date Range Filtering:
subscribedafter
: Filter subscribers who joined after this date (ISO 8601 format)subscribedbefore
: Filter subscribers who joined before this date (ISO 8601 format)emailedafter
: Filter subscribers who were emailed after this date (ISO 8601 format)emailedbefore
: Filter subscribers who were emailed before this date (ISO 8601 format)
Email Pattern Filtering:
email_contains
: Filter subscribers whose email contains the specified text
Tag-Based Filtering:
tags[]
: Filter subscribers by tags (supports multiple tags)tagmatchtype
: Determines how multiple tags are matchedany
: OR logic - returns subscribers with ANY of the specified tags (default)all
: AND logic - returns subscribers with ALL of the specified tags
Tag Filtering Logic Explanation:
When filtering by tags, you can control the matching logic using the tag_match_type
parameter:
OR Logic (default): Returns subscribers who have ANY of the specified tags.
AND Logic: Returns subscribers who have ALL of the specified tags.
Example: If you have subscribers with these tags:
- Alice:
["premium", "newsletter"]
- Bob:
["premium", "vip"]
- Carol:
["newsletter", "trial"]
- Dave:
["basic"]
OR Logic request tags[]=premium&tags[]=newsletter&tag_match_type=any
returns Alice, Bob, and Carol:
- ✅ Alice has both
premium
andnewsletter
(matches) - ✅ Bob has
premium
(matches one of the requested tags) - ✅ Carol has
newsletter
(matches one of the requested tags) - ❌ Dave has neither
premium
nornewsletter
AND Logic request tags[]=premium&tags[]=newsletter&tag_match_type=all
returns only Alice:
- ✅ Alice has both
premium
andnewsletter
(matches all required tags) - ❌ Bob has
premium
but notnewsletter
- ❌ Carol has
newsletter
but notpremium
- ❌ Dave has neither
premium
nornewsletter
Custom Data Filtering:
customdata[fieldname]
: Filter by custom JSONB field values
Request Examples
Basic request:
GET /api/v1/subscribers.json?page=1
Filter by subscription status:
GET /api/v1/subscribers.json?subscription_status=unsubscribed
Filter by source and activity status:
GET /api/v1/subscribers.json?subscription_status=active&source=website
Filter by date range:
GET /api/v1/subscribers.json?subscribed_after=2024-01-01T00:00:00Z&subscribed_before=2024-12-31T23:59:59Z
Filter by tags (OR logic - subscribers with ANY of these tags):
GET /api/v1/subscribers.json?tags[]=premium&tags[]=newsletter&tag_match_type=any
Filter by tags (AND logic - subscribers with ALL of these tags):
GET /api/v1/subscribers.json?tags[]=premium&tags[]=newsletter&tag_match_type=all
Filter by tags (default behavior - OR logic when tag_match_type
is omitted):
GET /api/v1/subscribers.json?tags[]=premium&tags[]=newsletter
Filter by custom data:
GET /api/v1/subscribers.json?custom_data[plan]=enterprise
Combined filtering:
GET /api/v1/subscribers.json?subscription_status=active&source=api&subscribed_after=2024-01-01T00:00:00Z&tags[]=premium
Response
{
"subscribers": [
{
"id": "123",
"email": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"ip_address": "192.168.1.1",
"is_active": true,
"source": "web_form",
"subscribed_at": "2024-03-20T10:00:00Z",
"unsubscribed_at": null,
"last_email_sent_at": "2024-03-25T14:30:00Z",
"created_at": "2024-03-20T10:00:00Z",
"tags": ["newsletter", "product-updates"],
"custom_data": { "some_key": "some value" }
}
],
"pagination": {
"total": 1500,
"count": 250,
"from": 1,
"to": 250,
"current": 1,
"total_pages": 6
}
}
Find Subscriber
This endpoint can be used to find a subscriber by email address and to return the details stored in your Broadcast database.
GET /api/v1/subscribers/find.json
Parameters
email
(required): Email address of the subscriber
Request
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
https://your-broadcast-domain.com/api/v1/subscribers/[email protected]
Response
{
"id": "123",
"email": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"ip_address": "192.168.1.1",
"is_active": true,
"source": "web_form",
"subscribed_at": "2024-03-20T10:00:00Z",
"unsubscribed_at": null,
"last_email_sent_at": "2024-03-25T14:30:00Z",
"created_at": "2024-03-20T10:00:00Z",
"tags": ["newsletter", "product-updates"],
"custom_data": { "some_key": "some value" }
}
Create Subscriber
This endpoint can be used to create a new subscriber.
Parameters
The following parameters need to be “namespaced” under the subscriber
key. See the cURL example for an example.
email
(required): Email address of the subscriberfirst_name
: First name of the subscriberlast_name
: Last name of the subscriberip_address
: IP address of the subscriberis_active
: Indicates if the subscriber is activesource
: Source of the subscribersubscribed_at
: Timestamp when the subscriber was addedtags
: Array of tags to add to the subscriber
Request
curl -X POST \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
--data-raw '{
"subscriber": {
"email": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"ip_address": "192.168.1.1",
"is_active": true,
"source": "web_form",
"subscribed_at": "2024-03-20T10:00:00Z",
"tags": ["newsletter", "product-updates"],
"custom_data": {
"my_custom_data": "data value"
}
}
}' \
https://your-broadcast-domain.com/api/v1/subscribers.json
Note that when adding a tags
array, you must send an array of strings.
Response
The response code will be 201 (Created) if the subscriber was created successfully.
If a subscriber already exists in the system (eg. such as if a subscriber is added and is unsubscribed), the response will also be 201. Note that in this case, the system will assume that the subscriber has re-subscribed and will set the unsubscribed_at field as null. Any attributes passed along to the API will also be updated at the same time.
If the request is invalid, the response code will be 422 (Unprocessable Entity). The error message will be returned in the response body.
Example of an error response:
{
"errors": {
"email": ["has already been taken"]
}
}
Update Subscriber
This endpoint can be used to update a subscriber details.
Parameters
The parameters are the same as the create subscriber endpoint, but only the fields you want to update need to be included in the request.
Again, the parameters need to be “namespaced” under the subscriber
key. See the cURL example for an example.
Request
curl -X PATCH \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
--data-raw '{
"email": "[email protected]",
"subscriber": {
"email": "[email protected]"
}
}' \
https://your-broadcast-domain.com/api/v1/subscribers.json
Note that the endpoint does not fully fit with typical RESTful conventions, as we include the email address as part of the parameters to identify the subscriber record.
Response
The response code will be 200 (OK) and will return the subscriber JSON object.
If the request is invalid, the response code will be 422 (Unprocessable Entity). The error message will be returned in the response body.
Deactivate Subscriber
You can deactivate a subscriber using the following endpoint:
POST /api/v1/subscribers/deactivate.json
Parameters
email
(required): Email address of the subscriber to deactivate
The parameter can be either passed directly or namespaced under the subscriber
key. See the cURL example for an example.
Request
curl -X POST \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
--data-raw '{
"email": "[email protected]"
}' \
https://your-broadcast-domain.com/api/v1/subscribers/deactivate.json
Response
The response code will be 200 (OK) if the subscriber was successfully deactivated.
Activate Subscriber
This endpoint allows you to reactivate a previously deactivated subscriber.
POST /api/v1/subscribers/activate.json
Parameters
email
(required): Email address of the subscriber to activate
The parameter can be either passed directly or namespaced under the subscriber
key. See the cURL example for an example.
Request
curl -X POST \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
--data-raw '{
"email": "[email protected]"
}' \
https://your-broadcast-domain.com/api/v1/subscribers/activate.json
Response
The response code will be 200 (OK) if the subscriber was successfully activated.
Add Tags To Subscriber
This endpoint allows you to add one or more tags to a subscriber.
POST /api/v1/subscribers/add_tag.json
Parameters
email
(required): Email address of the subscribertags
(required): An array of tags to add to the subscriber
The parameter can be either passed directly or namespaced under the subscriber
key. See the cURL example for an example.
Request
curl -X POST \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
--data-raw '{
"email": "[email protected]",
"tags": ["newsletter", "product-updates"]
}' \
https://your-broadcast-domain.com/api/v1/subscribers/add_tag.json
Response
The response code will be 200 (OK) if the tags were successfully added.
Remove Tags From Subscriber
This endpoint allows you to remove one or more tags from a subscriber.
DELETE /api/v1/subscribers/remove_tag.json
Parameters
email
(required): Email address of the subscribertags
(required): An array of tags to remove from the subscriber
The parameter can be either passed directly or namespaced under the subscriber
key. See the cURL example for an example.
Request
curl -X DELETE \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
--data-raw '{
"email": "[email protected]",
"tags": ["newsletter"]
}' \
https://your-broadcast-domain.com/api/v1/subscribers/remove_tag.json
Response
The response code will be 200 (OK) if the tags were successfully removed.