Subscription Topics

Let contacts manage their email preferences with subscription topics. Instead of a binary subscribe/unsubscribe, contacts can opt into specific categories like “Product Updates” or “Marketing”.

POST

/subscription-topics

Create a new subscription topic.

json

{
  "name": "Product Updates",
  "description": "New features, improvements, and release notes"
}

GET

/subscription-topics

List all subscription topics.

json

{
  "topics": [
    {
      "id": 1,
      "name": "Product Updates",
      "description": "New features, improvements, and release notes",
      "created_at": "2026-03-23T10:00:00.000Z"
    },
    {
      "id": 2,
      "name": "Marketing",
      "description": "Promotions, offers, and company news",
      "created_at": "2026-03-20T10:00:00.000Z"
    }
  ]
}

DELETE

/subscription-topics/:id

Delete a subscription topic. Contacts subscribed to this topic are not deleted.

json

{
  "success": true
}

Managing Contact Subscriptions

Manage which topics a specific contact is subscribed to. Endpoints are organized under the contact's ID:

GET

/subscription-topics/contacts/:contactId/subscriptions

List all topic subscriptions for a specific contact.

json

{
  "subscriptions": [
    {
      "topic_id": "top_xyz789ghi012",
      "contact_id": "con_abc123def456",
      "subscribed_at": "2026-03-23T10:00:00.000Z"
    },
    {
      "topic_id": "top_jkl345mno678",
      "contact_id": "con_abc123def456",
      "subscribed_at": "2026-03-24T08:00:00.000Z"
    }
  ]
}

POST

/subscription-topics/contacts/:contactId/subscriptions

Subscribe a contact to a topic. Both contactId in the path and topic_id in the body are publicId strings (con_*, top_*), not integers.

json

{
  "topic_id": "top_xyz789ghi012"
}

DELETE

/subscription-topics/contacts/:contactId/subscriptions/:topicId

Unsubscribe a contact from a topic.

json

{
  "success": true
}

Using Topics with Broadcasts

When creating a broadcast, set the topic_id to only send to contacts subscribed to that topic. This ensures contacts only receive emails they have opted into.

typescript

// Only contacts subscribed to "Product Updates" will receive this
const { broadcast } = await poststack.broadcasts.create({
  name: 'New Feature: Workflows',
  from: 'updates@yourdomain.com',
  subject: 'Introducing Workflows',
  html: '<p>Automate your email sequences...</p>',
  segment_id: 'seg_all_users',
  topic_id: 1,
});