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 status
    • subscribed: 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 matched
    • any: 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 and newsletter (matches)
  • ✅ Bob has premium (matches one of the requested tags)
  • ✅ Carol has newsletter (matches one of the requested tags)
  • ❌ Dave has neither premium nor newsletter

AND Logic request tags[]=premium&tags[]=newsletter&tag_match_type=all returns only Alice:

  • ✅ Alice has both premium and newsletter (matches all required tags)
  • ❌ Bob has premium but not newsletter
  • ❌ Carol has newsletter but not premium
  • ❌ Dave has neither premium nor newsletter

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 subscriber
  • first_name: First name of the subscriber
  • last_name: Last name of the subscriber
  • ip_address: IP address of the subscriber
  • is_active: Indicates if the subscriber is active
  • source: Source of the subscriber
  • subscribed_at: Timestamp when the subscriber was added
  • tags: 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 subscriber
  • tags (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 subscriber
  • tags (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.