A topic is a subscription category — "Product updates," "Promotions" — that a contact can opt out of. It's independent of the global unsubscribe: a contact can stay on your list but silence one kind of mail.

Opt-in vs. opt-out

The default_opt_in field decides what happens for a contact who has never touched the topic:

• default_opt_in: true (the default) — an opt-out topic. Contacts are auto-enrolled unless they opt out.
• default_opt_in: false — an opt-in topic. Contacts are silent until they explicitly subscribe.

Managing topics

Create, list, update, and archive topics under /api/v1/topics. Deleting a topic archives it (soft): it disappears from pickers, but campaigns that used it keep their history.

# Create an opt-out newsletter topic
curl https://www.unitpost.com/api/v1/topics \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Product updates", "default_opt_in": true }'

# Opt a contact out of it (id or email in the path)
curl -X PUT https://www.unitpost.com/api/v1/contacts/customer@acme.com/topics \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "topic_id": "top_123", "subscribed": false }'

Per-contact preferences

GET /api/v1/contacts/{id}/topics returns a contact's effective subscription for every topic — folding in each topic's default so you get the real answer, not just rows they've touched. PUT the same path with { topic_id, subscribed } to set one. The path accepts a contact id or email; an unknown topic returns 404. This is the same thing a contact does by toggling a topic on the unsubscribe preference page.

Scoping a campaign

Pass topic_id when you create a campaign to scope it. At send, contacts opted out of that topic are skipped (and counted as suppressed in the validate report) — on top of the usual segment-membership and global-unsubscribe checks. You can't point a campaign at an archived or missing topic: create and edit return a 409, and validate/send report a TOPIC_ARCHIVED or TOPIC_MISSING blocker.