Sign in Create account
Audience

Topics API

Subjects a contact chooses to receive or not, with an opt-in or opt-out default.

Topics are the subjects a contact chooses to receive or not, such as "Product updates" or "Surveys". They appear on the preferences page the contact opens from the unsubscribe link. For each topic, a contact has its own choice (opt_in or opt_out) or, if it has not chosen, the topic's default (default_subscription).

FieldValues
default_subscriptionopt_in: anyone who has not chosen receives it. opt_out: only those who chose to receive it do. It cannot change after the topic is created.
visibilitypublic: appears on the preferences page. private (default): only you manage it, through the API or the dashboard.

#List topics

GET/topics

Full-access key

paused_by_plan is true when the plan no longer covers the topic (for example, after a downgrade): it is still listed and can be read or deleted, but cannot be changed (403 paused_by_plan).

Query parameters

  • limitinteger
    From 1 to 100. Default: 20.
  • afterstring
    Cursor for the next page.
  • beforestring
    Cursor for the previous page.
GET /topics

cURL

curl https://api.postal.so/topics \
  -H "Authorization: Bearer $POSTAL_API_KEY"

Node.js

const response = await fetch('https://api.postal.so/topics', {
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
  },
});

const data = await response.json();

Python

import os
import requests

response = requests.get(
    "https://api.postal.so/topics",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    timeout=10,
)

data = response.json()

PHP

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->get('topics', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
]);

$data = json_decode($response->getBody(), true);
200Response
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "topic",
      "id": "019a1d95-4c5d-7e6f-8a7b-8c9d0e1f2a3b",
      "paused_by_plan": false,
      "name": "Product updates",
      "description": "Launches and offers, once a week.",
      "default_subscription": "opt_in",
      "visibility": "public",
      "created_at": "2026-10-20T10:05:00.000000Z",
      "updated_at": "2026-10-20T10:05:00.000000Z"
    }
  ]
}

#Create a topic

POST/topics

Full-access key

Request body

  • namestringrequired
    Name, up to 255 characters.
  • default_subscriptionstringrequired
    opt_in or opt_out.
  • descriptionstring | null
    Description shown to the contact, up to 500 characters.
  • visibilitystring
    public or private (default).

Errors

  • 422validation_error
    A field is invalid. The message says which one.
  • 403plan_limit_reached
    The plan does not allow more topics.
POST /topics

cURL

curl -X POST https://api.postal.so/topics \
  -H "Authorization: Bearer $POSTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product updates",
    "description": "Launches and offers, once a week.",
    "default_subscription": "opt_in",
    "visibility": "public"
  }'

Node.js

const response = await fetch('https://api.postal.so/topics', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Product updates',
    description: 'Launches and offers, once a week.',
    default_subscription: 'opt_in',
    visibility: 'public',
  }),
});

const data = await response.json();

Python

import os
import requests

response = requests.post(
    "https://api.postal.so/topics",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    json={
        "name": "Product updates",
        "description": "Launches and offers, once a week.",
        "default_subscription": "opt_in",
        "visibility": "public",
    },
    timeout=10,
)

data = response.json()

PHP

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->post('topics', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
    'json' => [
        'name' => 'Product updates',
        'description' => 'Launches and offers, once a week.',
        'default_subscription' => 'opt_in',
        'visibility' => 'public',
    ],
]);

$data = json_decode($response->getBody(), true);
201Response
{
  "object": "topic",
  "id": "019a1d95-4c5d-7e6f-8a7b-8c9d0e1f2a3b"
}

#Get a topic

GET/topics/{id}

Full-access key

Path parameters

  • idstringrequired
    Topic ID.

Errors

  • 404not_found
    The resource does not exist or belongs to another team.
GET /topics/{id}

cURL

curl https://api.postal.so/topics/019a1d95-4c5d-7e6f-8a7b-8c9d0e1f2a3b \
  -H "Authorization: Bearer $POSTAL_API_KEY"

Node.js

const response = await fetch('https://api.postal.so/topics/019a1d95-4c5d-7e6f-8a7b-8c9d0e1f2a3b', {
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
  },
});

const data = await response.json();

Python

import os
import requests

response = requests.get(
    "https://api.postal.so/topics/019a1d95-4c5d-7e6f-8a7b-8c9d0e1f2a3b",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    timeout=10,
)

data = response.json()

PHP

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->get('topics/019a1d95-4c5d-7e6f-8a7b-8c9d0e1f2a3b', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
]);

$data = json_decode($response->getBody(), true);
200Response
{
  "object": "topic",
  "id": "019a1d95-4c5d-7e6f-8a7b-8c9d0e1f2a3b",
  "paused_by_plan": false,
  "name": "Product updates",
  "description": "Launches and offers, once a week.",
  "default_subscription": "opt_in",
  "visibility": "public",
  "created_at": "2026-10-20T10:05:00.000000Z",
  "updated_at": "2026-10-20T10:05:00.000000Z"
}

#Update a topic

PATCH/topics/{id}

Full-access key

Changes the name, description or visibility. default_subscription cannot change, because contacts without a choice already follow the current default.

Path parameters

  • idstringrequired
    Topic ID.

Request body

  • namestring
    New name.
  • descriptionstring | null
    New description.
  • visibilitystring
    public or private.

Errors

  • 422validation_error
    Invalid field or an attempt to change default_subscription.
  • 403paused_by_plan
    The topic is paused because it is over the plan's limit.
  • 404not_found
    The resource does not exist or belongs to another team.
PATCH /topics/{id}

cURL

curl -X PATCH https://api.postal.so/topics/019a1d95-4c5d-7e6f-8a7b-8c9d0e1f2a3b \
  -H "Authorization: Bearer $POSTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "visibility": "private"
  }'

Node.js

const response = await fetch('https://api.postal.so/topics/019a1d95-4c5d-7e6f-8a7b-8c9d0e1f2a3b', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    visibility: 'private',
  }),
});

const data = await response.json();

Python

import os
import requests

response = requests.patch(
    "https://api.postal.so/topics/019a1d95-4c5d-7e6f-8a7b-8c9d0e1f2a3b",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    json={
        "visibility": "private",
    },
    timeout=10,
)

data = response.json()

PHP

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->patch('topics/019a1d95-4c5d-7e6f-8a7b-8c9d0e1f2a3b', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
    'json' => [
        'visibility' => 'private',
    ],
]);

$data = json_decode($response->getBody(), true);
200Response
{
  "object": "topic",
  "id": "019a1d95-4c5d-7e6f-8a7b-8c9d0e1f2a3b"
}

#Delete a topic

DELETE/topics/{id}

Full-access key

Removes the topic and the contacts' choices about it.

Path parameters

  • idstringrequired
    Topic ID.

Errors

  • 404not_found
    The resource does not exist or belongs to another team.
DELETE /topics/{id}

cURL

curl -X DELETE https://api.postal.so/topics/019a1d95-4c5d-7e6f-8a7b-8c9d0e1f2a3b \
  -H "Authorization: Bearer $POSTAL_API_KEY"

Node.js

const response = await fetch('https://api.postal.so/topics/019a1d95-4c5d-7e6f-8a7b-8c9d0e1f2a3b', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
  },
});

const data = await response.json();

Python

import os
import requests

response = requests.delete(
    "https://api.postal.so/topics/019a1d95-4c5d-7e6f-8a7b-8c9d0e1f2a3b",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    timeout=10,
)

data = response.json()

PHP

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->delete('topics/019a1d95-4c5d-7e6f-8a7b-8c9d0e1f2a3b', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
]);

$data = json_decode($response->getBody(), true);
200Response
{
  "object": "topic",
  "id": "019a1d95-4c5d-7e6f-8a7b-8c9d0e1f2a3b",
  "deleted": true
}