---
title: "Marketing topics namespace"
label: "Marketing topics"
description: "Reference for listing a board's marketing topics for newsletter sign-up forms."
publishedAt: 2026-11-16
order: 17
status: "published"
---

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`](/docs/sdk/reference/top-level-methods).

## 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`

```ts no-check
board.marketingTopics.list(
  options?: FetchOptions,
): Promise<MarketingTopicListEnvelope>
```

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.

```ts
const { data: topics } = await board.marketingTopics.list();
const { name } = await board.context();

await board.subscribe({
  email,
  consent: true,
  consentText: `Send me news and offers from ${name}.`,
  source: 'blog-footer',
  topics: topics.filter((topic) => ticked.has(topic.key)).map((t) => t.key),
});
```

Each `MarketingTopic` contains:

| Field | Type | Behavior |
| --- | --- | --- |
| `object` | `'marketing_topic'` | Resource discriminator. |
| `key` | `string` | The stable key to send in `board.subscribe({ topics })`. It never changes once the topic exists. |
| `name` | `string` | The 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.
