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 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
`redacted` Boolean indicating if the subscriber’s PII has been redacted

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" },
      "redacted": false
    }
  ],
  "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" },
  "redacted": false
}

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
  • 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.

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

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": "web_form",
  "subscribed_at": "2024-03-20T10:00:00Z",
  "unsubscribed_at": "2024-03-25T15:30:00Z",
  "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" },
  "redacted": false
}

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": "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" },
  "redacted": false
}

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