---
title: Topics
description: Subscription categories that let recipients choose what they receive.
---

A topic is a category of mail, such as "Product updates", "Newsletter" or "Promotions". Recipients can leave one topic and stay subscribed to the rest. Manage topics in the dashboard under **Audience → Topics**, or through the API.

Each topic has a `default_subscription`, set when you create it and not changeable later:

- `opt_in`: every contact is subscribed unless they opt out.
- `opt_out`: a contact is subscribed only after they opt in.

A topic also has a `visibility`. A `public` topic is listed on the unsubscribe page, and a `private` one appears only through its own link.

## How topics apply

- **Broadcasts.** A broadcast can target a topic. It goes to the contacts who are subscribed to that topic (their own choice, or the topic default). Contacts who are unsubscribed team-wide, or who left the sending domain, are always left out.
- **Single emails.** Send an email with a `topic_id` and it respects that topic. If every `to` address has opted out, the send returns `422 all_recipients_suppressed`.
- **Unsubscribe page.** The page lists the public topics, so a recipient can switch one off or leave all marketing mail from that domain. Mail sent without a `topic_id` and outside a broadcast is never affected. See [Unsubscribes](/docs/concepts/unsubscribes).

A topic that a broadcast uses, or that an email still waiting to send used, cannot be deleted: the call returns `409 conflict` until those have gone out or been canceled.

```sh
curl -X POST "https://api.billionsend.com/topics" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Product updates", "default_subscription": "opt_in" }'
```

You set a contact's choices with `PATCH /contacts/{id}/topics`, passing entries like `{ "id": "<topic-id>", "subscription": "opt_in" }`. `GET /contacts/{id}/topics` lists every topic with the contact's `subscription` and an `explicit` flag (false when it is the topic default).

## One topic per brand

If each of your domains is its own brand, bind a topic to the domain it belongs to by setting `domain_id`, when you create it or later with `PATCH /topics/{id}`, or by picking the domain in the dashboard.

- A bound topic is listed only on that domain's unsubscribe page. No other domain's page shows its name.
- A send with that `topic_id` must come from that domain. From any other, `POST /emails` and the broadcast calls return `422`.
- A topic with no domain is listed on every domain's page and can be sent from any domain. `"domain_id": null` makes a bound topic team-wide again.
- A domain cannot be deleted while topics are bound to it (`409`).

[Segments](/docs/concepts/segments) can be bound the same way.

## API keys limited to a domain

An API key limited to one domain can only create topics bound to that domain, and cannot make one team-wide.
