Subscribers API

The Subscribers API allows you to programmatically manage your subscriber list.

Required Permissions

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

  • List and read subscribers (Read)
  • Create and update subscribers (Write)

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
`created_at` The date and time the subscriber was created
`tags` An array of tags associated with the subscriber

List Subscribers

GET /api/v1/subscribers.json

Parameters

  • page: The page number to return (default is 1)

Request

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://your-broadcast-domain.com/api/v1/subscribers.json?page=1

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,
      "created_at": "2024-03-20T10:00:00Z",
      "tags": ["newsletter", "product-updates"]
    }
  ],
  "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,
  "created_at": "2024-03-20T10:00:00Z",
  "tags": ["newsletter", "product-updates"]
}

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