Skip to main content
Topics represent categories of communication, such as product updates, newsletters, security notices, or account announcements. They give your team a stable preference model without tying those preferences to a specific campaign or broadcast.

​
Topic settings

Each topic has:
  • a name,
  • an optional description,
  • a default_subscription of opt_in or opt_out,
  • a visibility of public or private.
The default subscription determines the starting preference for contacts that do not yet have an explicit subscription for that topic.

​
Public and private topics

Visibility describes how a topic is intended to be exposed in preference experiences. Use public topics for preferences that customers may be allowed to manage themselves. Use private topics for internal or application-controlled categories that should not appear as normal customer-facing choices.

​
Topics are not segments

Topics describe what kind of communication a contact wants to receive. Segments describe which contacts belong to a target audience. A contact can be in a segment and still be opted out of the relevant topic. That distinction becomes important when determining final delivery eligibility.

​
Changing a topic

A topic’s name, description, and visibility can change over time. Its default_subscription is part of the topic’s preference model and should be chosen deliberately when the topic is created.

​
Pagination

GET /topics uses limit and offset pagination. It does not use cursor parameters such as after or before.
  • limit defaults to 50 when omitted or non-positive.
  • A limit greater than 100 resets to the default 50 rather than being clamped to 100.
  • offset defaults to 0, and negative values are treated as 0.
  • Malformed integer values for limit or offset return 400 Bad Request.
The list response includes object: "list", a data array, and has_more. The server fetches one extra record internally to determine has_more without exposing that lookahead record in the page. To walk the list, increase offset by the number of records returned and continue while has_more is true. For endpoint details, request fields, and responses, see the Topics section in the API Reference.