TRtrycourier
Preference Topics

Create Topic in Section

Changed on

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

post/preferences/sections/{section_id}/topics

Request

Path parameters

section_idstring required

Id of the workspace preference to create the topic in.

Headers

Idempotency-Keystring

A unique key that makes this request idempotent. If Courier receives another request with the same Idempotency-Key, it returns the stored response from the first request without performing the operation again (including the original status code and any error). Use it to safely retry POST requests after network failures without risking duplicate sends. The key is scoped to this endpoint.

x-idempotency-expirationstring

How long the idempotency key remains valid, as a Unix epoch timestamp in seconds or an ISO 8601 date string. Only applies when Idempotency-Key is provided. If omitted, the key is retained for 25 hours; the maximum is 1 year.

Request body

namestring required

Human-readable name for the preference topic.

descriptionstring nullable

Optional description shown under the topic on the hosted preferences page.

default_status'OPTED_OUT' | 'OPTED_IN' | 'REQUIRED' required
routing_optionsChannelClassification[] nullable

Default channels delivered for this topic. Defaults to empty if omitted.

allowed_preferencesAllowedPreference[] nullable

Preference controls a recipient may customize for this topic. Defaults to empty if omitted.

include_unsubscribe_headerboolean nullable

Whether to include a list-unsubscribe header on emails for this topic.

topic_dataobject nullable

Arbitrary metadata associated with the topic.

Response

Created

idstring required

The preference topic id.

namestring required

Human-readable name.

descriptionstring nullable

Optional description shown under the topic on the hosted preferences page.

default_status'OPTED_OUT' | 'OPTED_IN' | 'REQUIRED' required
routing_optionsChannelClassification[] required

Default channels delivered for this topic. May be empty.

allowed_preferencesAllowedPreference[] required

Preference controls a recipient may customize. May be empty.

include_unsubscribe_headerboolean required

Whether a list-unsubscribe header is included on emails for this topic.

topic_dataobject required

Arbitrary metadata associated with the topic.

createdstring required

ISO-8601 timestamp of when the topic was created.

creatorstring nullable

Id of the creator.

updatedstring required

ISO-8601 timestamp of the last update.

updaterstring nullable

Id of the last updater.

Changes

  • f76bed79a913Revision changes
    • info

      api tag Preference Topics added

    • info

      api tag Workspace Preferences removed

    • info

      added the new optional header request parameter Idempotency-Key

    • info

      added the new optional header request parameter x-idempotency-expiration

  • 49e3cc128b6cRevision changes
    • info

      added the new optional request property

    • info

      added the optional property to the response with the status