Marketing topics namespace

Reference for listing a board's marketing topics for newsletter sign-up forms.

Use board.marketingTopics to build a newsletter sign-up form with a checkbox per topic, such as a weekly newsletter or hiring tips. Send the ticked keys with board.subscribe.

Shared behavior

The method is a public read. It returns the Board API wire body unchanged and throws BoardApiError for a non-2xx response. Its trailing FetchOptions passes abort signals, headers, and framework cache directives through to fetch.

board.marketingTopics.list

Returns the board's live topics, oldest first. A board has at most 20, so the list is never paginated. It is empty when the board sends all its marketing email to one list.

Each MarketingTopic contains:

FieldTypeBehavior
object'marketing_topic'Resource discriminator.
keystringThe stable key to send in board.subscribe({ topics }). It never changes once the topic exists.
namestringThe label to show next to the checkbox. The board can rename it.

Topics on a sign-up

  • A sign-up that sends topics gets only those topics.
  • A sign-up without topics gets every topic the board has set to add new marketing sign-ups.
  • A key that is not one of the board's live topics rejects the call with subscribe_unknown_topic (400), naming the key in details.key. Refresh the list and render the form again.

Topics wait for the person's confirmation click, like the rest of the sign-up. Someone whose address already receives the board's marketing gets them straight away.