Subscribers API

The Subscribers API lets you manage the people on your email lists. You can create and update subscribers, manage their tags, control their subscription status, and query your list with powerful filters.

Base URL

https://app.sendbroadcast.com/api/v1

Authentication

All requests require a Bearer token with the appropriate subscriber permissions. See Authentication for details.

The Subscriber Object

Field Type Description
id integer Unique identifier for the subscriber
email string The subscriber’s email address
first_name string First name
last_name string Last name
ip_address string IP address captured at signup
is_active boolean Whether the subscriber is active and eligible to receive emails
source string How the subscriber was added (e.g., api_subscription, import, form)
subscribed_at datetime When the subscriber originally subscribed
unsubscribed_at datetime When the subscriber unsubscribed (null if subscribed)
confirmed_at datetime When the subscriber confirmed via double opt-in (null if unconfirmed or not applicable)
confirmation_status string Confirmation state: "confirmed" or "unconfirmed". Derived from confirmed_at.
created_at datetime When the record was created
tags array List of tag names assigned to the subscriber
custom_data object Arbitrary key-value data stored as JSON

Example Subscriber Object

{
  "id": 42,
  "email": "[email protected]",
  "first_name": "Jane",
  "last_name": "Doe",
  "ip_address": "203.0.113.50",
  "is_active": true,
  "source": "api_subscription",
  "subscribed_at": "2025-01-15T10:30:00.000Z",
  "unsubscribed_at": null,
  "confirmed_at": null,
  "confirmation_status": "unconfirmed",
  "created_at": "2025-01-15T10:30:00.000Z",
  "tags": ["newsletter", "premium"],
  "custom_data": {
    "plan": "pro",
    "company": "Acme Inc"
  }
}

List Subscribers

Retrieve a paginated list of subscribers with optional filters.

GET /api/v1/subscribers.json

Query Parameters

Parameter Type Description
is_active string Filter by active status. "true" or "false".
source string Filter by source (e.g., api_subscription, import).
email string Partial email match (case-insensitive). "@example" matches all addresses at that domain.
confirmation_status string Filter by confirmation status. "confirmed" or "unconfirmed".
created_after string ISO 8601 datetime. Only subscribers created on or after this time.
created_before string ISO 8601 datetime. Only subscribers created on or before this time.
tags array Tags the subscriber must have. Uses AND logic – the subscriber must have all specified tags.
custom_data object Filter by custom data fields. Values are matched exactly against the subscriber’s custom_data JSON. Numeric strings are coerced to numbers, "true"/"false" to booleans.
page integer Page number (default: 1).

Response

The response includes a subscribers array and a pagination object. Each page returns up to 250 subscribers.

Example Request

curl -X GET "https://app.sendbroadcast.com/api/v1/subscribers.json?is_active=true&tags[]=newsletter&tags[]=premium" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response

{
  "broadcast_channel_id": 1,
  "subscribers": [
    {
      "id": 42,
      "email": "[email protected]",
      "first_name": "Jane",
      "last_name": "Doe",
      "ip_address": null,
      "is_active": true,
      "source": "api_subscription",
      "subscribed_at": "2025-01-15T10:30:00.000Z",
      "unsubscribed_at": null,
      "confirmed_at": null,
      "confirmation_status": "unconfirmed",
      "created_at": "2025-01-15T10:30:00.000Z",
      "custom_data": {},
      "tags": ["newsletter", "premium"]
    }
  ],
  "pagination": {
    "total": 1,
    "count": 1,
    "from": 1,
    "to": 1,
    "current": 1,
    "total_pages": 1
  }
}

Filtering by Custom Data

Pass custom_data as nested parameters. The API uses PostgreSQL JSONB containment (@>), so the subscriber’s custom_data must contain all the key-value pairs you specify.

curl -X GET "https://app.sendbroadcast.com/api/v1/subscribers.json?custom_data[plan]=pro&custom_data[active]=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Find a Subscriber by Email

Look up a single subscriber by their exact email address.

GET /api/v1/subscribers/[email protected]

Query Parameters

Parameter Type Required Description
email string Yes The subscriber’s email address.

Example Request

curl -X GET "https://app.sendbroadcast.com/api/v1/subscribers/[email protected]" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response

Returns the full subscriber object (see The Subscriber Object above).

Error Response

{
  "error": "Subscriber not found"
}

Status: 404 Not Found

Create a Subscriber

Add a new subscriber to your channel. If a subscriber with the same email already exists, this endpoint updates them instead and reactivates their subscription.

POST /api/v1/subscribers.json

Request Body

Parameters are nested under a subscriber key.

Parameter Type Required Description
subscriber[email] string Yes Email address.
subscriber[first_name] string No First name.
subscriber[last_name] string No Last name.
subscriber[ip_address] string No IP address.
subscriber[source] string No Defaults to api_subscription for new subscribers.
subscriber[subscribed_at] datetime No Override the subscription timestamp.
subscriber[tags] array No Tags to assign. Pass as an array: ["tag1", "tag2"].
subscriber[custom_data] object No Arbitrary key-value pairs.

Important: Use tags (array), not tag_list. The API will reject requests that include tag_list.

Example Request

curl -X POST "https://app.sendbroadcast.com/api/v1/subscribers.json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber": {
      "email": "[email protected]",
      "first_name": "Jane",
      "last_name": "Doe",
      "tags": ["newsletter", "premium"],
      "custom_data": {
        "plan": "pro",
        "company": "Acme Inc"
      }
    }
  }'

Response

Status: 201 Created

Returns the full subscriber object.

Error Response

{
  "errors": {
    "email": ["is invalid"]
  }
}

Status: 422 Unprocessable Content

Create a Subscriber with Double Opt-In

Create a subscriber that requires email confirmation before becoming active. A confirmation email is sent using the channel’s default confirmation template.

POST /api/v1/subscribers.json

Request Body

Parameter Type Required Description
double_opt_in boolean or object Yes Set to true or pass an object with options (e.g., { "reply_to": "[email protected]" }).
confirmation_template_id integer No ID of a specific confirmation template. Can also be passed inside the double_opt_in object. Falls back to the channel’s default.

All standard subscriber parameters (subscriber[email], subscriber[first_name], etc.) are also accepted.

Extended double_opt_in options

Instead of passing true, you can pass an object to customize the confirmation email:

Option Type Description
reply_to string Reply-to email address for the confirmation email.
confirmation_template_id integer ID of a specific confirmation template to use.
include_unsubscribe_link boolean Include unsubscribe link/footer in the confirmation email. Default: true.

Example Request

curl -X POST "https://app.sendbroadcast.com/api/v1/subscribers.json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber": {
      "email": "[email protected]",
      "first_name": "Jane"
    },
    "double_opt_in": true
  }'

With options:

curl -X POST "https://app.sendbroadcast.com/api/v1/subscribers.json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber": {
      "email": "[email protected]",
      "first_name": "Jane"
    },
    "double_opt_in": {
      "reply_to": "[email protected]",
      "confirmation_template_id": 456
    }
  }'

Response

Status: 201 Created

{
  "id": 42,
  "email": "[email protected]",
  "first_name": "Jane",
  "confirmed_at": null,
  "confirmation_status": "pending",
  "confirmation_url": "https://app.sendbroadcast.com/confirm/abc123token"
}

Behavior

Subscriber State Behavior
New Created unconfirmed. Confirmation email sent.
Exists, unconfirmed New confirmation created. Fresh confirmation email sent.
Exists, confirmed double_opt_in ignored. Subscriber returned as-is.

Update a Subscriber

Update an existing subscriber’s details. The subscriber is identified by their email address.

PATCH /api/v1/subscribers.json

Request Body

Parameters are nested under a subscriber key. The email field identifies which subscriber to update.

Parameter Type Required Description
subscriber[email] string Yes Email of the subscriber to update.
subscriber[first_name] string No Updated first name.
subscriber[last_name] string No Updated last name.
subscriber[ip_address] string No Updated IP address.
subscriber[source] string No Updated source.
subscriber[tags] array No Replaces existing tags entirely.
subscriber[custom_data] object No Replaces existing custom data entirely.

Example Request

curl -X PATCH "https://app.sendbroadcast.com/api/v1/subscribers.json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber": {
      "email": "[email protected]",
      "first_name": "Janet",
      "custom_data": {
        "plan": "enterprise"
      }
    }
  }'

Response

Returns the updated subscriber object.

Error Responses

Status Description
404 Not Found No subscriber with that email exists.
422 Unprocessable Content Validation errors (e.g., invalid email format).

Deactivate a Subscriber

Set a subscriber’s is_active to false. The subscriber stays in your list but will not receive broadcasts or sequence emails.

POST /api/v1/subscribers/deactivate.json

Request Body

Parameter Type Required Description
email string Yes Email of the subscriber to deactivate.

Example Request

curl -X POST "https://app.sendbroadcast.com/api/v1/subscribers/deactivate.json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Response

Returns the updated subscriber object with is_active: false.

Activate a Subscriber

Set a subscriber’s is_active to true, making them eligible to receive emails again.

POST /api/v1/subscribers/activate.json

Request Body

Parameter Type Required Description
email string Yes Email of the subscriber to activate.

Example Request

curl -X POST "https://app.sendbroadcast.com/api/v1/subscribers/activate.json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Response

Returns the updated subscriber object with is_active: true.

Add Tags

Add one or more tags to a subscriber without removing existing tags.

POST /api/v1/subscribers/add_tag.json

Request Body

Parameter Type Required Description
email string Yes Email of the subscriber.
tags array Yes Tags to add.

Example Request

curl -X POST "https://app.sendbroadcast.com/api/v1/subscribers/add_tag.json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "tags": ["vip", "early-adopter"]
  }'

Response

Returns the updated subscriber object with the new tags merged into the existing tag list.

Remove Tags

Remove one or more tags from a subscriber.

DELETE /api/v1/subscribers/remove_tag.json

Request Body

Parameter Type Required Description
email string Yes Email of the subscriber.
tags array Yes Tags to remove.

Example Request

curl -X DELETE "https://app.sendbroadcast.com/api/v1/subscribers/remove_tag.json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "tags": ["early-adopter"]
  }'

Response

Returns the updated subscriber object with the specified tags removed.

Error Response

{
  "error": "tags parameter is required"
}

Status: 422 Unprocessable Entity

Unsubscribe a Subscriber

Mark a subscriber as unsubscribed. This sets unsubscribed_at to the current time and is_active to false.

POST /api/v1/subscribers/unsubscribe.json

Request Body

Parameter Type Required Description
email string Yes Email of the subscriber to unsubscribe.

Example Request

curl -X POST "https://app.sendbroadcast.com/api/v1/subscribers/unsubscribe.json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Response

Returns the updated subscriber object with is_active: false and unsubscribed_at set.

Resubscribe a Subscriber

Resubscribe a previously unsubscribed subscriber. This clears unsubscribed_at and sets is_active to true.

POST /api/v1/subscribers/resubscribe.json

Request Body

Parameter Type Required Description
email string Yes Email of the subscriber to resubscribe.

Example Request

curl -X POST "https://app.sendbroadcast.com/api/v1/subscribers/resubscribe.json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Response

Returns the updated subscriber object with is_active: true and unsubscribed_at: null.

Redact a Subscriber (GDPR)

Permanently redact a subscriber’s personally identifiable information for GDPR compliance. This is an irreversible operation.

POST /api/v1/subscribers/redact.json

Request Body

Parameter Type Required Description
email string Yes Email of the subscriber to redact.

What Gets Removed

  • Email address (replaced with a redacted placeholder)
  • First name and last name
  • IP address
  • Custom data

What Gets Preserved

  • Campaign delivery statistics and engagement metrics
  • The subscriber record itself (in a redacted state)
  • Historical broadcast recipient data for analytics

Example Request

curl -X POST "https://app.sendbroadcast.com/api/v1/subscribers/redact.json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Response

{
  "message": "Subscriber successfully redacted"
}

Status: 200 OK

Error Response

{
  "error": "Failed to redact subscriber: ..."
}

Status: 422 Unprocessable Content

Unsubscribe vs. Deactivate

These two operations serve different purposes:

  Unsubscribe Deactivate
Sets is_active to false Yes Yes
Sets unsubscribed_at Yes No
Meaning The subscriber opted out. Honors their explicit request to stop receiving emails. An administrative action. The subscriber is paused but did not request to leave.
Reversible with resubscribe activate

Use unsubscribe when the subscriber has asked to stop receiving emails. Use deactivate for administrative purposes like pausing a subscriber during a data cleanup.

Error Responses

Status Code Description
401 Unauthorized Missing or invalid API token, or token lacks subscriber permissions.
404 Not Found Subscriber with the given email does not exist.
422 Unprocessable Content Validation errors or invalid parameters.

Next: Broadcasts API - Send and manage email campaigns via API.