Subscription topics
Split lifecycle email into streams a recipient can opt out of individually.
A topic is a named stream of lifecycle email — "Product updates", "Weekly digest", "Special offers". Topics let a recipient leave one stream without leaving all of them, which keeps an unsubscribe from costing you every future email to that contact.
Topics apply to lifecycle email only. Transactional email — receipts, password resets — is never topic-scoped and never blocked by an unsubscribe.
Declaring a topic
A topic is a kebab-case key set on a lifecycle template:
{ "slug": "weekly-digest", "category": "lifecycle", "topic": "weekly-digest" }Topics self-register: the first time a template declares one, it's added to
the project's topic registry with a title-cased display name (special-offers →
"Special Offers"). You can refine the name and description later — in the
dashboard under Settings → Topics, or with
POST /api/v1/topics — and a curated label is
never overwritten by a later template.
A lifecycle template with no topic sits in the global lifecycle bucket: an unsubscribe from it opts the recipient out of all lifecycle email.
How opt-out is scoped
Suppression rows carry the topic they apply to. A lifecycle send of topic T is
blocked by either a global unsubscribe or a topic-T unsubscribe:
| Recipient has | weekly-digest send | special-offers send | Receipt (transactional) |
|---|---|---|---|
| No suppression | Delivers | Delivers | Delivers |
Unsubscribed from weekly-digest | Blocked | Delivers | Delivers |
| Global unsubscribe | Blocked | Blocked | Delivers |
| Bounce / complaint / manual | Blocked | Blocked | Blocked |
Bounce, complaint, and manual suppressions are always written globally and block everything — they're a deliverability signal, not a preference. See Suppression & unsubscribe.
The preference center
Every lifecycle email links to a hosted preference page. What it shows depends on whether the project has defined topics:
- Topics defined — the recipient gets a per-topic toggle list, plus "unsubscribe from everything" and a resubscribe-all option.
- No topics defined — a single global opt-out, with resubscribe.
One-click unsubscribe (the RFC 8058 header) always applies to the topic of the
message the recipient clicked from, so leaving the digest doesn't silently
cancel their receipts. Resubscribing only ever removes an unsubscribe
suppression — it can't clear a bounce or complaint.
Changing a live template's topic re-scopes future sends, but it does not
migrate existing suppressions. A contact who opted out of weekly-digest is
not opted out of a topic you rename it to.