---
title: "Create Topic in Section"
method: POST
path: "/preferences/sections/{section_id}/topics"
tags: ["Preference Topics"]
---

# Create Topic in Section

`POST /preferences/sections/{section_id}/topics`

Creates a subscription topic inside a workspace preference. The default status sets whether users start opted in, opted out, or required.

## Path parameters

- `section_id` string, required

## Headers

- `Idempotency-Key` string
- `x-idempotency-expiration` string

## Request body

- WorkspacePreferenceTopicCreateRequest — Request body for creating a preference topic.
  - `name` string, required — Human-readable name for the preference topic.
  - `description` string, nullable — Optional description shown under the topic on the hosted preferences page.
  - `default_status` 'OPTED_OUT' | 'OPTED_IN' | 'REQUIRED', required
  - `routing_options` ChannelClassification[], nullable — Default channels delivered for this topic. Defaults to empty if omitted.
  - `allowed_preferences` AllowedPreference[], nullable — Preference controls a recipient may customize for this topic. Defaults to empty if omitted.
  - `include_unsubscribe_header` boolean, nullable — Whether to include a list-unsubscribe header on emails for this topic.
  - `topic_data` object, nullable — Arbitrary metadata associated with the topic.

## Response `201`

Created

- WorkspacePreferenceTopicGetResponse — A subscription preference topic in your workspace.
  - `id` string, required — The preference topic id.
  - `name` string, required — Human-readable name.
  - `description` string, nullable — Optional description shown under the topic on the hosted preferences page.
  - `default_status` 'OPTED_OUT' | 'OPTED_IN' | 'REQUIRED', required
  - `routing_options` ChannelClassification[], required — Default channels delivered for this topic. May be empty.
  - `allowed_preferences` AllowedPreference[], required — Preference controls a recipient may customize. May be empty.
  - `include_unsubscribe_header` boolean, required — Whether a list-unsubscribe header is included on emails for this topic.
  - `topic_data` object, required — Arbitrary metadata associated with the topic.
  - `created` string, required — ISO-8601 timestamp of when the topic was created.
  - `creator` string, nullable — Id of the creator.
  - `updated` string, required — ISO-8601 timestamp of the last update.
  - `updater` string, nullable — Id of the last updater.

## Other responses

- `400` — Bad Request
- `404` — Not Found

## Changes

- **2026-07-29** `f76bed79a913` — 4 info
  - api tag `Preference Topics` added
  - api tag `Workspace Preferences` removed
  - added the new optional `header` request parameter `Idempotency-Key`
  - added the new optional `header` request parameter `x-idempotency-expiration`
- **2026-07-09** `49e3cc128b6c` — 2 info
  - added the new optional request property `description`
  - added the optional property `description` to the response with the `201` status
- **2026-06-26** `61131080b185` — 3 info
  - api operation id `preferenceSections_topics_create` removed and replaced with `workspacePreferences_topics_create`
  - api tag `Workspace Preferences` added
  - api tag `Preference Sections` removed
- **2026-06-24** `124a60dd716b` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/trycourier/apis/courier/changes/preferences/sections/:section_id/topics/post.md)

---

[API](https://skmtc.dev/trycourier/apis/courier.md) · [All operations](https://skmtc.dev/trycourier/apis/courier/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/trycourier/courier/revisions/cb8586034158/schema)