Topics and preferences

A topic is a kind of mail a person can opt out of on its own — newsletters, product updates, tips. The argument for them is complaint rate, not tidiness. Given only all-or-nothing, a person who wants fewer newsletters but still wants their invoice reminders often presses spam instead, and a complaint costs the sending domain far more than an opt-out. Letting them opt down keeps them reachable.

Defining topics

POST /v1/topics takes a key (lower-case letters, digits and hyphens), a name, an optional description shown on the preference page, and default_subscribed. Posting an existing key updates it. The default is on, which suits an existing product newsletter; default-off suits anything a person should have to ask for.

DELETE /v1/topics/{key} removes the topic and every preference recorded against it. Anyone who had opted out loses that record, so this is more destructive than the name suggests.

curl -X POST https://api.example.com/v1/topics \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"key": "newsletter", "name": "Monthly newsletter", "default_subscribed": true}'

Where a preference lives

A preference is stored on (workspace, email, topic), never on a contact row. It belongs to the person, not to whichever audience they happen to be in: someone on two lists has one opinion about newsletters. Deleting a contact keeps their preferences for the same reason — an opt-out has to outlive the contact record, or the next import silently puts them back.

An absent row means the person has never chosen, and the topic's default applies. Defaults are deliberately not written out as rows for everyone: doing so would freeze today's default against a topic whose default later changes, so changing it would move nobody who never chose.

Reading and setting preferences

GET /v1/topics/preferences?email= returns every topic with subscribed already resolved — the person's choice where there is one, the default where there is not. Check it before asking why someone is not getting a particular kind of email; an opt-out looks identical to a delivery failure from the outside.

POST /v1/topics/preferences with an email and a topics map of key to boolean sets several at once; an unknown key is 422 unknown_topic. Only do this when the person has actually asked. Silently re-subscribing someone who opted out is what generates spam complaints.

POST /v1/topics/{key}/import with emails (up to 50,000) and subscribed is the migration path: an existing provider knows who opted out of which list, and that has to arrive here before the first send.

curl -X POST https://api.example.com/v1/topics/preferences \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"email": "ana@example.com", "topics": {"newsletter": false, "product-updates": true}}'

Sending under a topic

Pass topic on POST /v1/emails, or topic_key when creating a campaign. A recipient who has opted out of that topic is skipped: the send returns 202 with skipped: true and a reason of unsubscribed_from_topic:<key>, recorded in the log rather than dropped silently. An unknown topic key skips too, so a typo cannot bypass every preference someone has set.

The topic is checked after suppression because it is the finer of the two. A marketing-wide opt-out already covers every topic; opting out of one topic must leave the others reachable.

The unsubscribe page

Marketing mail carries a one-click unsubscribe header and a footer link to /api/unsubscribe, signed per workspace and address so a link minted by one tenant cannot opt someone out of another's mail. When the message was sent under a topic the link carries it, and one click opts the person out of that kind of mail only — then shows the preference page with the rest, so they can adjust. The one-click POST that mailbox providers send is honoured the same way.

"Unsubscribe from everything" on that page, or a one-click on a message with no topic, is the full opt-out: a marketing-scope suppression, every pending scheduled send cancelled, every automation enrolment ended, and every topic switched off so the page reflects reality.

Transactional mail is unaffected