Topics
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_idand it respects that topic. If everytoaddress has opted out, the send returns422 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_idand outside a broadcast is never affected. See 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.
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_idmust come from that domain. From any other,POST /emailsand the broadcast calls return422. - A topic with no domain is listed on every domain’s page and can be sent from any domain.
"domain_id": nullmakes a bound topic team-wide again. - A domain cannot be deleted while topics are bound to it (
409).
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.