Topics

List topics

GET/api/v1/email/topics

GET /email/topics
curl -X GET 'https://www.unitpost.com/api/v1/email/topics' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "topic",
      "id": "id_123",
      "name": "Example",
      "description": "string",
      "channel": "email",
      "default_opt_in": false,
      "subscriber_count": 1,
      "unsubscribed_count": 1,
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Retrieve a list of your subscription topics, cursor-paginated. A topic is a category of email (e.g. Product updates, Promotions) that recipients can opt out of without leaving your list entirely. Pass ?archived=true to list archived topics instead. Create one with Create a topic, or check a contact's preferences with List a contact's topic subscriptions. Requires the topics:read capability.

Parameters4 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
archivedboolean · queryWhen true, list only archived topics instead of active ones.
Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
descriptionrequiredstring | null—
channelrequiredenumemail | smsWhich channel the topic belongs to. Email topics are managed under `/email/topics`, SMS topics under `/sms/topics`.
default_opt_inrequiredboolean—
subscriber_countintegerContacts subscribed to this topic, among those the channel can reach (an email address, or an SMS number): for an opt-out topic everyone but those who opted out of it, for an opt-in topic those who opted in. A send also skips contacts unsubscribed from everything and suppressed addresses. The dashboard's count.
unsubscribed_countintegerReachable contacts who opted out of this topic.
created_atrequiredstring—
updated_atrequiredstring—
200401422503

Create a topic

POST/api/v1/email/topics

POST /email/topics
curl -X POST 'https://www.unitpost.com/api/v1/email/topics' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Product updates",
    "default_opt_in": true
  }'
Response · 201
{
  "object": "topic",
  "id": "id_123",
  "name": "Example",
  "description": "string",
  "channel": "email",
  "default_opt_in": false,
  "subscriber_count": 1,
  "unsubscribed_count": 1,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Create a subscription topic — a category recipients can opt out of on their own (e.g. Promotions) while staying on your list. default_opt_in decides whether contacts with no explicit preference are treated as subscribed. Scope a campaign to a topic so opted-out contacts are skipped automatically via Create a campaign, and set an individual contact's preference with Set a contact's topic preference. Topics differ from segments: a segment decides who a campaign targets, a topic lets recipients opt out. Requires the topics:write capability.

Request body3 fields
FieldTypeDescription
namerequiredstring—
descriptionstring—
default_opt_inboolean—
Response · 201 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
descriptionrequiredstring | null—
channelrequiredenumemail | smsWhich channel the topic belongs to. Email topics are managed under `/email/topics`, SMS topics under `/sms/topics`.
default_opt_inrequiredboolean—
subscriber_countintegerContacts subscribed to this topic, among those the channel can reach (an email address, or an SMS number): for an opt-out topic everyone but those who opted out of it, for an opt-in topic those who opted in. A send also skips contacts unsubscribed from everything and suppressed addresses. The dashboard's count.
unsubscribed_countintegerReachable contacts who opted out of this topic.
created_atrequiredstring—
updated_atrequiredstring—
201401409422

Retrieve a topic

GET/api/v1/email/topics/{id}

GET /email/topics/{id}
curl -X GET 'https://www.unitpost.com/api/v1/email/topics/top_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "topic",
  "id": "id_123",
  "name": "Example",
  "description": "string",
  "channel": "email",
  "default_opt_in": false,
  "subscriber_count": 1,
  "unsubscribed_count": 1,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Retrieve a single topic by id, including its name and default_opt_in setting. Change it with Update a topic, or list every topic with List topics. Requires the topics:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
descriptionrequiredstring | null—
channelrequiredenumemail | smsWhich channel the topic belongs to. Email topics are managed under `/email/topics`, SMS topics under `/sms/topics`.
default_opt_inrequiredboolean—
subscriber_countintegerContacts subscribed to this topic, among those the channel can reach (an email address, or an SMS number): for an opt-out topic everyone but those who opted out of it, for an opt-in topic those who opted in. A send also skips contacts unsubscribed from everything and suppressed addresses. The dashboard's count.
unsubscribed_countintegerReachable contacts who opted out of this topic.
created_atrequiredstring—
updated_atrequiredstring—
200401404503

Update a topic

PATCH/api/v1/email/topics/{id}

PATCH /email/topics/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/email/topics/top_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "topic",
  "id": "id_123",
  "name": "Example",
  "description": "string",
  "channel": "email",
  "default_opt_in": false,
  "subscriber_count": 1,
  "unsubscribed_count": 1,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Update a topic's name or default_opt_in behavior, or pass { "archived": true | false } to archive or restore it. Only explicit choices are stored, so changing default_opt_in subscribes (true) or unsubscribes (false) every contact with no explicit choice on the topic at once; Unitpost-Warning names how many. Archiving a topic hides it and stops it from being targeted, but is blocked with 409 while an active campaign still targets it. To manage a single contact's preference, use Set a contact's topic preference. Requires the topics:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body3 fields
FieldTypeDescription
namestring—
descriptionstring | null—
default_opt_inboolean—
Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
descriptionrequiredstring | null—
channelrequiredenumemail | smsWhich channel the topic belongs to. Email topics are managed under `/email/topics`, SMS topics under `/sms/topics`.
default_opt_inrequiredboolean—
subscriber_countintegerContacts subscribed to this topic, among those the channel can reach (an email address, or an SMS number): for an opt-out topic everyone but those who opted out of it, for an opt-in topic those who opted in. A send also skips contacts unsubscribed from everything and suppressed addresses. The dashboard's count.
unsubscribed_countintegerReachable contacts who opted out of this topic.
created_atrequiredstring—
updated_atrequiredstring—
200401404409422

Delete a topic

DELETE/api/v1/email/topics/{id}

DELETE /email/topics/{id}
curl -X DELETE 'https://www.unitpost.com/api/v1/email/topics/top_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

Archive a topic (a soft delete — existing subscription records are preserved so you can restore it later). It's blocked with 409 while an active campaign still targets it. Restore an archived topic by sending { "archived": false } to Update a topic. Requires the topics:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
204401404409

Opt contacts out of a topic

POST/api/v1/email/topics/{id}/opt-out

POST /email/topics/{id}/opt-out
curl -X POST 'https://www.unitpost.com/api/v1/email/topics/top_123/opt-out' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 202
{
  "object": "job",
  "id": "id_123",
  "kind": "string",
  "status": "QUEUED",
  "total": 1,
  "processed": 0,
  "failed": 0,
  "error": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z"
}

Opt many contacts out of this topic in one call, as a background job: the contacts you list (contact_ids or emails, up to 1,000, each a contact of this workspace) or every member of a segment (segment_id, however many; also needs segments:read). Send exactly one. Each contact is opted out as Set a contact's topic preference would: one that was subscribed gets a topic.unsubscribed webhook and an activity row naming your key; one already opted out is left as it is, with no webhook. Suppressions and other topics are untouched, and there is no bulk opt-in. Listed contacts are checked first: the first that isn't one of yours is a 404 naming it (details), and nothing starts. The answer is the job (202, Location); follow it with Retrieve a job. Pass an Idempotency-Key so a retry answers the same job instead of starting another. Requires the topics:write capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
Idempotency-Keystring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Request body3 fields
FieldTypeDescription
contact_idsstring[]Contacts of this workspace (`con_…`), up to 1,000.
emailsstring[]Contacts of this workspace by email address, up to 1,000.
segment_idstringEvery member of this segment (`seg_…`), however many. Also needs `segments:read`.
Response · 202 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
kindrequiredstring—
statusrequiredenumQUEUED | RUNNING | COMPLETED | FAILED | CANCELED—
totalrequiredinteger | null—
processedrequiredinteger—
failedrequiredinteger—
errorrequiredstring | null—
created_atrequiredstring—
completed_atrequiredstring | null—
202400401403404409422429502

List a contact's topic subscriptions

GET/api/v1/contacts/{id}/topics

GET /contacts/{id}/topics
curl -X GET 'https://www.unitpost.com/api/v1/contacts/con_123/topics' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "contact_topic",
      "topic_id": "topic_123",
      "channel": "email",
      "subscribed": false,
      "status": "subscribed",
      "source": "user"
    }
  ]
}

Retrieve a contact's effective subscription state for every active topic, cursor-paginated. Each row resolves the contact's explicit preference against the topic's default_opt_in, so subscribed is always the answer to "would this contact receive a campaign scoped to this topic?". Change a preference with Set a contact's topic preference. Requires the topics:read capability.

Parameters4 fields
FieldTypeDescription
idrequiredstring · path—
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
Response · 200 fields6 fields
FieldTypeDescription
objectrequiredstring—
topic_idrequiredstring—
channelrequiredenumemail | smsThe topic's channel: manage it under `/email/topics` or `/sms/topics`.
subscribedrequiredboolean—
statusrequiredenumsubscribed | unsubscribed—
sourcerequiredenumuser | manual | import | api—
200401404422

Set a contact's topic preference

POST/api/v1/contacts/{id}/topics

POST /contacts/{id}/topics
curl -X POST 'https://www.unitpost.com/api/v1/contacts/con_123/topics' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "topic_id": "top_123",
    "subscribed": false
  }'
Response · 201
{
  "object": "contact_topic",
  "topic_id": "topic_123",
  "channel": "email",
  "subscribed": false,
  "status": "subscribed",
  "source": "user"
}

Subscribe or unsubscribe a contact for one topic. This records an explicit preference that overrides the topic's default_opt_in, and it's idempotent — setting the same preference twice succeeds. PUT behaves identically. Read the contact's current state with List a contact's topic subscriptions; change several at once with Update a contact's topic preferences. Requires the topics:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body3 fields
FieldTypeDescription
topic_idstring—
topicstring—
subscribedrequiredboolean—
Response · 201 fields6 fields
FieldTypeDescription
objectrequiredstring—
topic_idrequiredstring—
channelrequiredenumemail | smsThe topic's channel: manage it under `/email/topics` or `/sms/topics`.
subscribedrequiredboolean—
statusrequiredenumsubscribed | unsubscribed—
sourcerequiredenumuser | manual | import | api—
201401404422

Update a contact's topic preferences

PATCH/api/v1/contacts/{id}/topics

PATCH /contacts/{id}/topics
curl -X PATCH 'https://www.unitpost.com/api/v1/contacts/con_123/topics' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "topics": [
      {
        "topic_id": "top_123",
        "subscribed": false
      },
      {
        "topic_id": "top_456",
        "subscribed": true
      }
    ]
  }'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "contact_topic",
      "topic_id": "topic_123",
      "channel": "email",
      "subscribed": false,
      "status": "subscribed",
      "source": "user"
    }
  ]
}

Subscribe or unsubscribe a contact for several topics in one call: topics lists up to 50 preferences, each topic once. Topics you leave out keep their current preference. The contact and every topic are checked before any preference is set, so an unknown topic is a 404 naming it and nothing changes. Each preference is then recorded as Set a contact's topic preference records one (topic.subscribed / topic.unsubscribed only when it actually changes), and it's idempotent. The answer lists the resolved subscriptions in the order sent. Any key other than topics, in the body or in an item, is a 422. Requires the topics:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body1 field
FieldTypeDescription
topicsrequiredobject[]The preferences to change, up to 50, each topic once. Topics left out keep theirs.
Response · 200 fields6 fields
FieldTypeDescription
objectrequiredstring—
topic_idrequiredstring—
channelrequiredenumemail | smsThe topic's channel: manage it under `/email/topics` or `/sms/topics`.
subscribedrequiredboolean—
statusrequiredenumsubscribed | unsubscribed—
sourcerequiredenumuser | manual | import | api—
200400401403404422

Set a contact's topic preference (alias of POST)

PUT/api/v1/contacts/{id}/topics

PUT /contacts/{id}/topics
# API: no generated example for PUT https://www.unitpost.com/api/v1/contacts/:id/topics
Response · 201
{
  "object": "contact_topic",
  "topic_id": "topic_123",
  "channel": "email",
  "subscribed": false,
  "status": "subscribed",
  "source": "user"
}

Identical to Set a contact's topic preference — provided so clients that prefer PUT semantics for an upsert can use it interchangeably. Requires the topics:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body3 fields
FieldTypeDescription
topic_idstring—
topicstring—
subscribedrequiredboolean—
Response · 201 fields6 fields
FieldTypeDescription
objectrequiredstring—
topic_idrequiredstring—
channelrequiredenumemail | smsThe topic's channel: manage it under `/email/topics` or `/sms/topics`.
subscribedrequiredboolean—
statusrequiredenumsubscribed | unsubscribed—
sourcerequiredenumuser | manual | import | api—
201401404422

Search docs and guides

Search the docs and product guides.