List Contact Topics

List all topics for the organization along with the contact's effective subscription status for each topic.

GET/contacts/{contact_id_or_email}/topics

Requires an API key with contacts:read permission.

Path Parameters

contact_id_or_emailstringrequired

The contact ID (UUID) or email address.

Query Parameters

limitnumber

Maximum number of results to return. Min 1, max 100. Default 20.

afterstring

Cursor for forward pagination.

beforestring

Cursor for backward pagination.

Response Fields

objectstring

Always "list".

has_moreboolean

Whether there are more results available.

dataarray

Array of topic subscription objects. Each item contains:

idstring

The topic ID.

namestring

The topic name.

descriptionstring | null

The topic description.

subscriptionstring

The contact's effective subscription: "opt_in" or "opt_out". Uses the topic's default_subscription if the contact has no explicit preference.

curl -X GET 'https://api.postflare.dev/contacts/e169aa45-1ecf-4183-9955-b1499d5701d3/topics' \
  -H 'Authorization: Bearer sk_xxxxxxxxx'

const response = await fetch(
  'https://api.postflare.dev/contacts/e169aa45-1ecf-4183-9955-b1499d5701d3/topics',
  {
    headers: {
      'Authorization': 'Bearer sk_xxxxxxxxx',
    },
  }
);

const data = await response.json();

Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Product Updates",
      "description": "Receive the latest product news",
      "subscription": "opt_in"
    }
  ]
}