Topics

Create a topic

key is the stable, project-unique name every preference form and integration refers to, so it survives a rename of name and cannot be edited afterwards.

default_opt_in is the field worth thinking about: it decides what SILENCE means for every contact who never answers. Leave it true for a topic introduced over a list you already have — those contacts consented to hear from you, and inventing an opt-out they never asked for would mute mail they expect. Set it false for anything a person has to ask for, and absence then means not asked rather than no.

Requires the topics:write scope — Create and edit topics, and change what your contacts are subscribed to — this decides who your campaigns reach.

post/api/v1/topics

Request

  • Base URL: https://api.sendly.now
  • URL: https://api.sendly.now/api/v1/topics
  • Auth: one of:
    • HTTP bearer
    • API key in cookie better-auth.session_token
    • OAuth 2 (authorization code, authorization URL https://app.sendly.now/api/auth/oauth2/authorize, token URL https://app.sendly.now/api/auth/oauth2/token, scopes: topics:write)

Request body

default_opt_inboolean
descriptionstring nullable
keystring required

Stable, URL-safe, unique within the project. This is what a preference form and an API caller name the topic by, so it must survive a rename of name — which is the whole reason it exists beside one.

namestring required

Response

The created topic

archivedboolean required

Hidden from the preference centre and from new sends, WITHOUT discarding the opt-outs recorded against it. There is no delete for the same reason: deleting a topic would delete the choices people made about it.

created_atstring date-time required
default_opt_inboolean required

What a contact with NO answer counts as. True is the honest default for a topic added after a list already exists: those contacts consented to hear from you, and inventing an opt-out they never asked for would silence mail they expect. False means the topic must be opted INTO, and absence means not asked rather than no.

descriptionstring nullable required
idstring required
keystring required

Stable, URL-safe, unique within the project. This is what a preference form and an API caller name the topic by, so it must survive a rename of name — which is the whole reason it exists beside one.

namestring required
subscribed_countinteger required

Contacts who explicitly said yes. Excludes those covered only by default_opt_in.

unsubscribed_countinteger required

Changes

No recorded changes to this operation across all 1 revision of this API.