Create Topic

Create a new subscription topic. Topics allow contacts to manage their email preferences.

POST/topics

Requires a full_access API key.

Body Parameters

namestringrequired

The topic name. Max 50 characters.

descriptionstring

A description of the topic. Max 200 characters.

default_subscriptionstring

The default subscription state for new contacts. Either "opt_in" or "opt_out". Default "opt_in".

visibilitystring

Whether the topic is visible to contacts in preference pages. Either "public" or "private". Default "public".

Response Fields

objectstring

Always "topic".

idstring

The ID of the newly created topic.

curl -X POST 'https://api.postflare.app/topics' \
  -H 'Authorization: Bearer re_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Product Updates",
    "description": "Receive the latest product news",
    "default_subscription": "opt_in",
    "visibility": "public"
  }'

const response = await fetch('https://api.postflare.app/topics', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer re_xxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Product Updates',
    description: 'Receive the latest product news',
    default_subscription: 'opt_in',
    visibility: 'public',
  }),
});

const data = await response.json();

Response

{
  "object": "topic",
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}