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, update, and redact subscribers (Write)

Common Use Cases

The filtering capabilities are particularly useful for:

  • External System Synchronization: Sync inactive users with your CRM by filtering is_active=false
  • Segment Management: Export specific subscriber segments based on tags, source, or activity status
  • Data Cleanup: Identify inactive subscribers using is_active=false
  • 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
`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:

Active Status Filtering:

  • is_active: Filter by active status
    • true: Subscribers marked as active
    • false: Subscribers marked as inactive

Source Filtering:

  • source: Filter by how the subscriber was added (e.g., api_subscription, opt_in_form, import)

Date Range Filtering:

  • created_after: Filter subscribers created after this date (ISO 8601 format)
  • created_before: Filter subscribers created before this date (ISO 8601 format)

Email Pattern Filtering:

  • email: Filter subscribers whose email contains the specified text (partial match, case-insensitive)

Tag-Based Filtering:

  • tags[]: Filter subscribers by tags (supports multiple tags with AND logic)

Tag Filtering Logic:

When filtering by multiple tags, subscribers must have ALL specified tags to be included in the results.

Example: If you have subscribers with these tags:

  • Alice: ["premium", "newsletter"]
  • Bob: ["premium", "vip"]
  • Carol: ["newsletter", "trial"]
  • Dave: ["basic"]

Request tags[]=premium&tags[]=newsletter 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:

  • custom_data[field_name]: Filter by custom JSONB field values

Request Examples

Basic request:

GET /api/v1/subscribers.json?page=1

Filter by active status:

GET /api/v1/subscribers.json?is_active=true

Filter by source and active status:

GET /api/v1/subscribers.json?is_active=true&source=api_subscription

Filter by date range:

GET /api/v1/subscribers.json?created_after=2024-01-01T00:00:00Z&created_before=2024-12-31T23:59:59Z

Filter by email pattern:

GET /api/v1/subscribers.json?email=gmail.com

Filter by tags (subscribers with ALL specified tags):

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?is_active=true&source=api_subscription&created_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": "api_subscription",
      "subscribed_at": "2024-03-20T10:00:00Z",
      "unsubscribed_at": null,
      "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/find.json?email=[email protected]

Response

{
  "id": "123",
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "ip_address": "192.168.1.1",
  "is_active": true,
  "source": "api_subscription",
  "subscribed_at": "2024-03-20T10:00:00Z",
  "unsubscribed_at": null,
  "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
  • is_active: Whether the subscriber is active (default: true)
  • tags: Array of tags to add to the subscriber
  • custom_data: JSON object with custom key-value pairs

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",
      "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.

Also note that is_active is automatically set to true when you add a subscriber. If the subscriber was previously set as not active, this will be overwritten and the subscriber will be changed to having is_active as true.

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’s details.

Parameters

  • email (required): The email address of the subscriber you want to update. This is used to identify the subscriber record.
  • subscriber (required): An object containing the fields you want to update.

The following fields can be updated inside the subscriber object:

  • email: New email address (only if you want to change it)
  • first_name: First name of the subscriber
  • last_name: Last name of the subscriber
  • is_active: Whether the subscriber is active
  • tags: Array of tags (replaces existing tags)
  • custom_data: JSON object with custom key-value pairs

Request Examples

Updating subscriber details (most common):

curl -X PATCH \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "email": "[email protected]",
    "subscriber": {
      "first_name": "Jane",
      "last_name": "Smith"
    }
  }' \
  https://your-broadcast-domain.com/api/v1/subscribers.json

Changing a subscriber’s email address:

When changing the email address, use the top-level email to identify the subscriber and subscriber.email for the new email:

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

Important Notes

  • The top-level email parameter is always required to identify which subscriber to update.
  • The subscriber.email field is only needed if you want to change the subscriber’s email address.
  • This endpoint does not follow typical RESTful conventions (e.g., /subscribers/:id). Instead, the subscriber is identified by their email address in the request body.

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.

Unsubscribe Subscriber

This endpoint allows you to unsubscribe a subscriber from your list. This sets the unsubscribed_at timestamp and marks the subscriber as inactive (is_active: false).

POST /api/v1/subscribers/unsubscribe.json

Parameters

  • email (required): Email address of the subscriber to unsubscribe

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/unsubscribe.json

Response

The response code will be 200 (OK) if the subscriber was successfully unsubscribed. The response includes the updated subscriber object with the unsubscribed_at timestamp set.

{
  "id": "123",
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "ip_address": "192.168.1.1",
  "is_active": false,
  "source": "api_subscription",
  "subscribed_at": "2024-03-20T10:00:00Z",
  "unsubscribed_at": "2024-03-25T15:30:00Z",
  "created_at": "2024-03-20T10:00:00Z",
  "tags": ["newsletter", "product-updates"],
  "custom_data": { "some_key": "some value" }
}

Resubscribe Subscriber

This endpoint allows you to resubscribe a previously unsubscribed subscriber. This clears the unsubscribed_at timestamp and marks the subscriber as active (is_active: true).

POST /api/v1/subscribers/resubscribe.json

Parameters

  • email (required): Email address of the subscriber to resubscribe

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/resubscribe.json

Response

The response code will be 200 (OK) if the subscriber was successfully resubscribed. The response includes the updated subscriber object with the unsubscribed_at field set to null.

{
  "id": "123",
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "ip_address": "192.168.1.1",
  "is_active": true,
  "source": "api_subscription",
  "subscribed_at": "2024-03-20T10:00:00Z",
  "unsubscribed_at": null,
  "created_at": "2024-03-20T10:00:00Z",
  "tags": ["newsletter", "product-updates"],
  "custom_data": { "some_key": "some value" }
}

Important Notes

  • Dual Field Management:
    • Unsubscribe sets unsubscribed_at timestamp AND marks subscriber as inactive (is_active: false)
    • Resubscribe clears unsubscribed_at (sets to null) AND marks subscriber as active (is_active: true)
  • Difference from Activate/Deactivate: The unsubscribe/resubscribe endpoints manage both subscription status (unsubscribed_at field) and activity status (is_active field), while activate/deactivate endpoints only manage the activity status (is_active field).

When to use Unsubscribe/Resubscribe: - Subscriber formally opts out of all communications (legal unsubscribe) - Compliance with anti-spam regulations (CAN-SPAM, GDPR, etc.) - Permanent removal from mailing lists - User clicks “unsubscribe” link in emails

When to use Activate/Deactivate: - Temporary pause of communications (subscriber vacation, busy period) - System-level deactivation (bounced emails, complaints, fraud detection) - Subscriber wants to pause but maintain their subscription status - Administrative actions that don’t constitute formal unsubscription - A/B testing scenarios where you temporarily exclude certain users - Webhook Events: Both endpoints trigger appropriate webhook events (subscriber.unsubscribed and subscriber.resubscribed) if you have webhooks configured. - Subscriber History: Both actions are logged in the subscriber’s history for audit purposes. - Idempotent Operations: These endpoints are safe to call multiple times - unsubscribing an already unsubscribed subscriber or resubscribing an already subscribed subscriber will not cause errors.

Redact Subscriber

This endpoint allows you to permanently redact a subscriber’s personally identifiable information (PII) while preserving campaign statistics. This is typically used for GDPR compliance or data privacy requirements.

⚠️ Warning: This action is irreversible. Once a subscriber is redacted, their personal data cannot be recovered.

POST /api/v1/subscribers/redact.json

What Gets Redacted

When a subscriber is redacted, the following information is permanently removed or anonymized:

  • Email address: Replaced with an anonymized identifier (redacted-{id}@privacy-compliant.local)
  • First and last names: Set to null
  • Custom data fields: Cleared completely
  • IP addresses: Removed
  • Preferences: Cleared

What Gets Preserved

The following data is preserved to maintain campaign analytics and statistical integrity:

  • Campaign statistics and metrics: Open rates, click rates, delivery statistics
  • Sequence performance data: Automation engagement metrics
  • Subscriber ID and timestamps: For referential integrity in reports
  • Aggregate reporting data: Overall campaign performance remains accurate

Parameters

  • email (required): Email address of the subscriber to redact

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/redact.json

Response

Success Response (200 OK)

{
  "message": "Subscriber successfully redacted"
}

Error Response (422 Unprocessable Entity)

{
  "error": "Failed to redact subscriber: [error details]"
}

Not Found Response (404 Not Found)

{
  "error": "Subscriber not found"
}

Important Considerations

  • Irreversible Action: Once redacted, subscriber data cannot be restored
  • Campaign Statistics: All historical email metrics remain intact for reporting
  • Compliance: Ideal for GDPR “right to be forgotten” requests
  • Database Integrity: The system maintains referential integrity across all related records
  • Audit Trail: The redaction action is logged for compliance purposes
  • Write Permission Required: Requires an API token with write permissions

Common Use Cases

  • GDPR Compliance: Responding to “right to be forgotten” requests
  • Data Minimization: Regularly cleaning PII while preserving analytics
  • Privacy Compliance: Meeting regulatory requirements for data retention
  • Customer Requests: Honoring explicit data deletion requests