Broadcast Docs
Back to main site
On this page

Subscriber Topics

A topic is one kind of email your subscribers can opt in to or out of: webinars, product updates, offers. Instead of one yes or no for your whole list, each subscriber has a choice per topic, and every email you send to a topic reaches only the people who chose it.

Topics change nothing until you use them. A channel with no topics, and every email sent without a topic, works exactly as before.

How a topic stores its value

You decide where each topic’s value lives. Broadcast does not invent a new field for it.

  • A custom data field. Pick a top-level key in the subscriber’s custom data, such as sub_webinars. The value is true, false, or not set. true, "true", 1 and "1" count as yes; any other value counts as no.
  • A tag. Pick a tag, such as webinars. Tagged subscribers receive the topic; everyone else does not.

Any other custom data stays private. Fields like origin or consent_basis never show to subscribers, because only the fields you turn into topics do.

Subscribers with no value

A subscriber who has never chosen has no value for the topic. Each topic has one setting for that case: Subscribers with no value either receive the topic or do not. New topics start as do not receive.

The setting is read when an email is sent. A value that is set always wins over it, and Broadcast never writes a default into a subscriber’s custom data. That means:

  • A contact created through the API, a form or an import keeps exactly the values you sent.
  • If you add a topic to an existing list and set it to receive, everyone who has not chosen yet keeps getting those emails, and anyone who says no is recorded as no.
  • If you may only email people who agreed to a topic, keep it at do not receive. A contact then gets that topic only after an explicit yes.

Warning

If some of your contacts may only receive certain topics (for example contacts from a partner who agreed to webinars only), keep every other topic at do not receive. Setting a topic to receive sends it to every contact with no value for it.

A tag topic has no explicit no: an untagged subscriber is simply not tagged. That is why a tag topic must stay at do not receive.

2.49+

A tag topic still remembers when the subscriber turned it off. The unsubscribe link, the one-click button and the preference page record that choice, so the tag cannot be added back by anyone else. See Only the subscriber turns a topic back on.

Setting up topics

Open Settings → Topics and click New topic.

  • Name is what subscribers see on the preference and unsubscribe pages. Description is optional and shows under the name on the preference page.
  • Where the value is stored: a custom data field or a tag. Both fields suggest the keys and tags your channel already uses.
  • Subscribers with no value: receive or do not receive (see above). An existing topic shows how many active subscribers have no value right now.
  • Show on the preference page: turn this off for a topic subscribers should not change themselves.
Settings, Topics: each topic with the field it reads and how many active subscribers have yes, no, no value, and receive it

The list shows, for each topic, how many active subscribers have yes, no and no value, and how many receive it. Use the arrows to set the order the preference page shows.

A topic in use

2.49+

A topic is in use while one of these uses it:

  • a broadcast that can still send: a draft, scheduled, sending, paused or failed broadcast that is not archived
  • a sequence
  • an opt-in form with a Topic block for it
  • a segment with a Topic rule for it

While a topic is in use:

  • Where the value is stored, the custom data field and the tag are locked, because a change would change who receives. The form names what uses the topic. Remove the topic from those first. The Topics API refuses the change with 422.
  • Subscribers with no value can still change, but the form warns you that the change changes who receives, and names the uses.
  • The topic cannot be deleted. The refusal names up to five uses, then “and N more”.

A sent, partly failed or aborted broadcast is not a use: it never sends again. Deleting the topic removes the topic from those broadcasts and goes ahead. An archived broadcast that can still send (an archived draft, for example) stops the delete, because unarchiving it would send it to everyone it targets. The refusal names it. Delete that broadcast, or remove the topic from it, first.

Sending to a topic

Broadcasts. On the Audience tab, choose a topic under Topic. The audience becomes your segments (or all subscribers) AND the topic. The live count and the Review tab show the result before you send. A tag topic works together with segments too.

2.49+

If no one in the audience receives the topic, the broadcast does not send. Send now and a scheduled send both stop with a message that names the topic: “This broadcast is for the topic “Webinars”, and no subscribers have that topic on.“

The broadcast Audience tab with the Topic select set to Webinars

Sequences. In a sequence’s settings, choose a topic. Each email step then reaches only enrolled subscribers who receive the topic; the others skip that email and carry on through the sequence. A subscriber who switches the topic off mid-sequence stops getting its emails from the next step.

On opt-in forms

Add a Topic block to an opt-in form to let new signups choose a topic. A ticked box stores yes, and an unticked box stores an explicit no, never "not set”. A tag topic adds its tag only when ticked. A subscriber who is already on the list keeps their topics when they submit the form, and changes them on the preference page. See Opt-In Forms.

2.49+

The form’s Add Tags setting counts as the subscriber’s own choice, because it applies only after their own signup or confirmation click. For an address that unsubscribed, a form always sends the confirmation email first, also without double opt-in (see Opt-In Forms). If one of those tags is a tag topic they turned off, the form adds it back and the topic is on again.

On the subscriber profile

2.48+

A subscriber’s page lists every topic of the channel with its value: On, Off or Not set. A tag topic shows On when tagged and Off when not. To change a value, click Edit and use the Topics section of the form. A tag topic is a checkbox. A custom data topic has On, Off and Not set. Not set removes the value, so the topic’s Subscribers with no value setting applies again; the option shows which way that goes, for example Not set (receives).

Each change is recorded in the subscriber’s activity with your email address, the topic, and its old and new value, and fires subscriber.preferences_updated. Editing topics never subscribes or unsubscribes the subscriber.

The Edit subscriber panel scrolled to Topics: Webinars set to Off with On and Not set locked and the note that only the subscriber can turn it back on, and a ticked Product updates checkbox for a tag topic

Only the subscriber turns a topic back on

2.49+

When a subscriber turns a topic off, only the subscriber can turn it on again. This applies to custom data topics and tag topics, on every path that changes a subscriber.

  • Custom data topic. The value stays false. Nothing else can set it to true or remove it.
  • Tag topic. Broadcast records that the subscriber turned it off: from the topic unsubscribe link, the one-click button, or the preference page. Nothing else can add the tag back. The tag is compared without regard to case, so Webinars and webinars are the same tag.

What each path does with a topic the subscriber turned off:

Path What happens
Subscriber profile On and Not set are locked for a custom data topic, and a tag topic’s checkbox is locked. A direct edit of the custom data or the tags is refused with an error.
Subscribers API (create, update, add tags) The topic stays off, the rest of the request is applied, and the response has a parameter_ignored warning that names the topic.
Import The topic stays off, the rest of the row is imported, and the import log names the row.
Sequence Add Tags step The other tags are added. The subscriber’s activity says which tag was not added and why.
Ask AI tagging The subscriber is skipped and counted as skipped.
Opt-in form Add Tags Added. The form applies its tags only after the subscriber’s own signup or confirmation click (a resubscribe always needs the click), so it counts as their choice.
Preference page, Resubscribe on the topic unsubscribed page Added. These are the subscriber’s own choice.

A subscriber who turns the topic on again clears the record. A full unsubscribe does not turn topics off, so it records nothing. Erasing a subscriber’s data deletes their records too.

In the Subscribers API, the subscriber’s topics shows a tag topic they turned off as false. A tag topic that is not tagged and was never turned off is null.

Warning

An opt-in form never changes the topics of a subscriber who is already on the list, through its Topic blocks. Its Add Tags setting is the exception above: it can turn a tag topic back on for a subscriber who confirms through the form.

In segments

2.48+

Add a rule with the field Topic, pick one of the channel’s topics, and choose an operator:

  • Receives: the subscribers an email sent to the topic reaches, including subscribers with no value when the topic is set to receive.
  • Does not receive: everyone else.
  • Is not set: subscribers with no value for the topic. Only for custom data topics.
The segment editor with one rule: Field Topic, Operator Receives, Value Webinars, and Matching: 6 subscribers in the footer

A segment rule and a topic send use the same check, so the two always agree. See Segments for the rule builder and Topic Field for the rule format.

2.49+

A topic that a segment rule uses cannot be deleted. Remove the rule first. See A topic in use.

Unsubscribing from a topic

On an email sent to a topic, the unsubscribe link and the one-click Unsubscribe button in Gmail and Yahoo turn off only that topic. The subscriber stays subscribed and keeps their other topics. The unsubscribe page names the topic and also offers Unsubscribe from everything and a link to the preference page.

You can change this in Settings → Unsubscribe Page → On an email sent to a topic: choose Unsubscribe from everything to make topic emails unsubscribe from the whole channel instead.

Emails with no topic, sequence emails and transactional emails always unsubscribe from everything, as before. See Unsubscribe Settings.

2.49+

After a topic unsubscribe, the page has a Resubscribe button. It turns that topic back on and changes nothing else, then shows a page that names the topic (“You’re subscribed to Webinars again”) with a button to turn it off again. If the topic is already off when the subscriber opens the link, they go straight to the topic unsubscribed page, with no confirmation step. You can change the button text under Settings → Unsubscribe Page → Page text → Topic unsubscribed page, and the page after it under Topic resubscribed page.

The preference page

Every subscriber has a hosted preference page where they switch topics on and off. Link to it with the {{ preferences_url }} merge tag in any broadcast or sequence email, or fill in Preference page link text on the footer block of the Drag-and-Drop Email Builder.

The preference page: a checkbox per topic, Save preferences, and Unsubscribe from everything
  • It shows only topics marked Show on the preference page, ticked when the subscriber receives them.
  • Saving records an explicit yes or no for each topic the subscriber changed. It never touches other custom data and never unsubscribes them.
  • Unsubscribe from everything is on the page too.
  • It uses the same branding, languages and custom text as your unsubscribe pages. Edit its text under Settings → Unsubscribe Page → Page text → Preference page.

The link is signed and personal, like the unsubscribe link. Anyone who has the email can use it, so do not forward emails that contain it.

Every change to a topic value is recorded in the subscriber’s activity and sent to your webhooks:

  • subscriber.preferences_updated lists each topic that changed with its old and new value, the time, and change_source: where the change came from (preference page, unsubscribe link, one-click unsubscribe, API, admin, import, opt-in form).
  • subscriber.updated still fires, now with change_source too.

See Webhooks for the payloads.

API and CLI

Manage topics with the Topics API or broadcast topics in the Agents CLI. Broadcasts and sequences take a topic_id, and the subscriber JSON shows each topic’s value. To change one topic without resending the whole custom data object, update the subscriber with "custom_data_mode": "merge".