Broadcast Docs
Back to main site

Topics API

A topic is one kind of email subscribers opt in to or out of. Read Subscriber Topics first: it explains how a topic’s value is stored and what “no value” means.

Required Permissions

Topics describe your subscribers’ preferences, so they use the subscriber permissions:

  • Subscribers read: list and get topics
  • Subscribers write: create, update and delete topics

Topic Object

  • storage: custom_data (the value is the top-level custom data key custom_data_key) or tag (the value is whether the subscriber has the tag tag_name).
  • unset_receives: whether a subscriber with no value receives the topic. Read at send time; Broadcast never writes it into custom data. Must be false for a tag topic.
  • visible_on_preference_page: whether subscribers can switch the topic themselves.
  • position: the order on the preference page.
JSON
{
  "id": 3,
  "name": "Webinars",
  "description": "Invitations to our webinars",
  "storage": "custom_data",
  "custom_data_key": "sub_webinars",
  "tag_name": null,
  "unset_receives": false,
  "visible_on_preference_page": true,
  "position": 1,
  "created_at": "2026-10-06T12:00:00Z",
  "updated_at": "2026-10-06T12:00:00Z"
}

List Topics

GET/api/v1/topics
cURL
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://your-broadcast-domain.com/api/v1/topics
JSON
{ "data": [ { "id": 3, "name": "Webinars", "...": "..." } ], "total": 1 }

Get Topic

GET/api/v1/topics/:id

Create Topic

POST/api/v1/topics

For a tag topic, send "storage": "tag" and "tag_name": "webinars". Returns 201 with the topic, or 422 with an error message.

cURL
curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "topic": {
      "name": "Webinars",
      "storage": "custom_data",
      "custom_data_key": "sub_webinars",
      "unset_receives": false
    }
  }' \
  https://your-broadcast-domain.com/api/v1/topics

Update Topic

PATCH /api/v1/topics/:id with the fields to change inside topic.

2.49+

While the topic is in use, storage, custom_data_key and tag_name cannot change, because a change would change who receives. A topic is in use while a broadcast that can still send (draft, scheduled, queueing, sending, paused, future scheduled or failed, and not archived), a sequence, an opt-in form or a segment rule uses it. The request returns 422, and the error names the uses:

A tag name that differs only in case is the same tag, so that change is allowed. The other fields, unset_receives included, can change while the topic is in use. A change to unset_receives changes who receives.

JSON
{
  "error": "The storage, custom data field and tag cannot change while the topic is in use, because that would change who receives. In use by: broadcast \"Spring launch\", segment \"Webinar audience\". Remove the topic from them first."
}

Delete Topic

DELETE/api/v1/topics/:id

2.49+

Returns 422 while the topic is in use, so a send never widens to everyone it targets. Segment rules count as a use. The error names up to five uses, then “and N more”:

A sent, partly failed or aborted broadcast is not a use: the delete removes the topic from it (its topic_id becomes null) and goes ahead. An archived broadcast that can still send (an archived draft, for example) also returns 422, with an error that names it, because unarchiving it would send it to everyone it targets. Deleting a topic does not change any subscriber data.

JSON
{
  "error": "The topic cannot be deleted while it is in use, because that would change who receives. In use by: sequence \"Onboarding\", opt-in form \"Footer\". Remove the topic from them first."
}

Example: from topic to segment

This workflow creates a topic, subscribes one subscriber to it, and builds a segment of everyone who receives it. The token needs Subscribers write for steps 1 and 2, and Segments write and Segments read for steps 3 and 4.

1. Create the topic.

The 201 response is the topic object. Keep its id for step 3; this example uses 3.

2. Subscribe a subscriber to the topic. A custom data topic’s value is the custom data key, so set sub_webinars to true. Use "custom_data_mode": "merge"; without it, the update replaces the whole custom_data object and removes the subscriber’s other keys.

The response is the subscriber, and its topics object now has "sub_webinars": true. For a subscriber who does not exist yet, send the same custom_data on create (POST /api/v1/subscribers.json). To unsubscribe from the topic later, send false. To go back to no value, send null, which deletes the key in merge mode.

3. Create a segment from the topic. A rule with "field": "topic" takes the topic ID as a string in value. You do not send rule_type: Broadcast sets it to topic.

receives matches exactly the subscribers a send to the topic reaches. With "unset_receives": false, as in step 1, that is only subscribers whose value is true. Use does_not_receive for everyone else, or not_set for subscribers with no value yet, for example to ask them to choose. A topic ID from another channel returns 422.

The response lists the matching subscribers, 250 per page. Jane is in it.

cURL
curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "topic": {
      "name": "Webinars",
      "description": "Invitations to our webinars",
      "storage": "custom_data",
      "custom_data_key": "sub_webinars",
      "unset_receives": false
    }
  }' \
  https://your-broadcast-domain.com/api/v1/topics
cURL
curl -X PATCH \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "email": "jane@example.com",
    "custom_data_mode": "merge",
    "subscriber": {
      "custom_data": { "sub_webinars": true }
    }
  }' \
  https://your-broadcast-domain.com/api/v1/subscribers.json
cURL
curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "segment": {
      "name": "Webinar audience",
      "description": "Subscribers who receive the Webinars topic",
      "segment_groups_attributes": [
        {
          "match_type": "all",
          "segment_rules_attributes": [
            { "field": "topic", "operator": "receives", "value": "3" }
          ]
        }
      ]
    }
  }' \
  https://your-broadcast-domain.com/api/v1/segments

4. Check who matches. The create response reports subscribers_count as 0. The count is recalculated when you get the segment:

cURL
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://your-broadcast-domain.com/api/v1/segments/SEGMENT_ID.json

Topics on other resources

2.49+

  • Subscribers: the subscriber JSON has topics, each topic’s stored value: true, false, or null for no value. A tag topic is true when tagged, false when the subscriber turned it off, and null otherwise. To change topic values, update custom_data or the tags; with "custom_data_mode": "merge" only the keys you send change. See Subscribers API.
  • Broadcasts and sequences: send topic_id on create or update. See Broadcasts API and Sequences API.
  • Segments: a segment rule with "field": "topic" and the topic ID as value matches the subscribers who receive the topic. See Topic Field.
  • Webhooks: subscriber.preferences_updated fires on every topic change. See Webhooks.