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 keycustom_data_key) ortag(the value is whether the subscriber has the tagtag_name).unset_receives: whether a subscriber with no value receives the topic. Read at send time; Broadcast never writes it into custom data. Must befalsefor a tag topic.visible_on_preference_page: whether subscribers can switch the topic themselves.position: the order on the preference page.
{ "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
/api/v1/topicscurl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ https://your-broadcast-domain.com/api/v1/topics
{ "data": [ { "id": 3, "name": "Webinars", "...": "..." } ], "total": 1 }
Get Topic
/api/v1/topics/:idCreate Topic
/api/v1/topicsFor a tag topic, send "storage": "tag" and "tag_name": "webinars". Returns 201 with the topic, or 422 with an error message.
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.
{ "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
/api/v1/topics/:idReturns 422 while a broadcast or sequence uses the topic, so a send never widens to everyone it targets. Remove the topic from them first. Deleting a topic does not change any subscriber data.
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.
{ "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 -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 -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 -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 -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ https://your-broadcast-domain.com/api/v1/segments/SEGMENT_ID.json
Topics on other resources
- Subscribers: the subscriber JSON has
topics, each topic’s stored value:true,false, ornullfor no value (a tag topic istrueornull). To change topic values, updatecustom_dataor the tags; with"custom_data_mode": "merge"only the keys you send change. See Subscribers API.
2.49+
- Subscribers: the subscriber JSON has
topics, each topic’s stored value:true,false, ornullfor no value. A tag topic istruewhen tagged,falsewhen the subscriber turned it off, andnullotherwise. To change topic values, updatecustom_dataor the tags; with"custom_data_mode": "merge"only the keys you send change. See Subscribers API.
- Broadcasts and sequences: send
topic_idon create or update. See Broadcasts API and Sequences API. - Segments: a segment rule with
"field": "topic"and the topic ID asvaluematches the subscribers who receive the topic. See Topic Field. - Webhooks:
subscriber.preferences_updatedfires on every topic change. See Webhooks.
Last updated
Was this page helpful?