---
title: "Topics"
description: "Subscription categories (e.g. Promotions) recipients can opt out of without leaving your list, independent of segment membership. Scope a campaign to a topic and opted-out contacts are skipped automatically."
url: https://www.unitpost.com/docs/api/topics
section: API reference
updated: 2026-07-31
---
# Topics

## Topics

> Subscription categories (e.g. Promotions) recipients can opt out of without leaving your list, independent of segment membership. Scope a campaign to a topic and opted-out contacts are skipped automatically.

Full schemas: [OpenAPI 3.1](https://www.unitpost.com/api/v1/openapi.json). HTML reference: https://www.unitpost.com/docs/api/topics.

## Operations

### `GET /api/v1/email/topics`

List topics

Retrieve a list of your subscription topics, cursor-paginated. A topic is a category of email (e.g. Product updates, Promotions) that recipients can opt out of without leaving your list entirely. Pass `?archived=true` to list archived topics instead. Create one with [Create a topic](#post-email-topics), or check a contact's preferences with [List a contact's topic subscriptions](#get-contacts-id-topics). Requires the `topics:read` capability.

### `POST /api/v1/email/topics`

Create a topic

Create a subscription topic — a category recipients can opt out of on their own (e.g. Promotions) while staying on your list. `default_opt_in` decides whether contacts with no explicit preference are treated as subscribed. Scope a campaign to a topic so opted-out contacts are skipped automatically via [Create a campaign](#post-email-campaigns), and set an individual contact's preference with [Set a contact's topic preference](#post-contacts-id-topics). Topics differ from segments: a [segment](#post-segments) decides who a campaign targets, a topic lets recipients opt out. Requires the `topics:write` capability.

### `GET /api/v1/email/topics/{id}`

Retrieve a topic

Retrieve a single topic by `id`, including its name and `default_opt_in` setting. Change it with [Update a topic](#patch-email-topics-id), or list every topic with [List topics](#get-email-topics). Requires the `topics:read` capability.

### `PATCH /api/v1/email/topics/{id}`

Update a topic

Update a topic's name or `default_opt_in` behavior, or pass `{ "archived": true | false }` to archive or restore it. Archiving a topic hides it and stops it from being targeted, but is blocked with `409` while an active campaign still targets it. To manage a single contact's preference, use [Set a contact's topic preference](#post-contacts-id-topics). Requires the `topics:write` capability.

### `DELETE /api/v1/email/topics/{id}`

Delete a topic

Archive a topic (a soft delete — existing subscription records are preserved so you can restore it later). It's blocked with `409` while an active campaign still targets it. Restore an archived topic by sending `{ "archived": false }` to [Update a topic](#patch-email-topics-id). Requires the `topics:write` capability.

### `GET /api/v1/contacts/{id}/topics`

List a contact's topic subscriptions

Retrieve a contact's effective subscription state for every active topic, cursor-paginated. Each row resolves the contact's explicit preference against the topic's `default_opt_in`, so `subscribed` is always the answer to "would this contact receive a campaign scoped to this topic?". Change a preference with [Set a contact's topic preference](#post-contacts-id-topics). Requires the `topics:read` capability.

### `POST /api/v1/contacts/{id}/topics`

Set a contact's topic preference

Subscribe or unsubscribe a contact for one topic. This records an explicit preference that overrides the topic's `default_opt_in`, and it's idempotent — setting the same preference twice succeeds. `PUT` behaves identically. Read the contact's current state with [List a contact's topic subscriptions](#get-contacts-id-topics). Requires the `topics:write` capability.

### `PUT /api/v1/contacts/{id}/topics`

Set a contact's topic preference (alias of POST)

Identical to [Set a contact's topic preference](#post-contacts-id-topics) — provided so clients that prefer `PUT` semantics for an upsert can use it interchangeably. Requires the `topics:write` capability.

## Related

- [Campaigns](https://www.unitpost.com/docs/api/campaigns): One-to-many sends to a segment or an inline recipient list. Draft, validate, schedule, send, pause, resume, and cancel — with a pre-send report that catches problems before anything goes out.
- [Templates](https://www.unitpost.com/docs/api/templates): Reusable email designs in the canonical block-based JSON format the dashboard editor produces, with per-recipient `{{variables}}` filled at send time.
- [Brand kits](https://www.unitpost.com/docs/api/brand-kits): Read-only Brand Kit profiles (voice, labeled colors, pinned library graphics, core pages) for on-brand template authoring. Writes and URL import stay in the dashboard (Settings → Brand).