Topics

Topics are subscription categories that contacts can opt in or out of. Use topics to let recipients control what types of emails they receive, such as "Marketing", "Product Updates", or "Weekly Digest".

Create a topic

POST
/v1/topics

Create a new subscription topic.

Request body

ParameterTypeDescription
namerequiredstringDisplay name for the topic.
cURL
curl -X POST https://api.txtly.com.au/v1/topics \
  -H "Authorization: Bearer tx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Product Updates"}'
Response — 201 Created
{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "name": "Product Updates",
  "subscriberCount": 0,
  "createdAt": "2026-03-21T00:00:00Z"
}

List topics

GET
/v1/topics

List all topics for the current team.

Example Response
{
  "data": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "name": "Product Updates",
      "subscriberCount": 128,
      "createdAt": "2026-03-21T00:00:00Z"
    }
  ]
}

Get a topic

GET
/v1/topics/{id}

Retrieve a topic by ID including subscriber count.

Update a topic

PATCH
/v1/topics/{id}

Update the topic name.

Delete a topic

DELETE
/v1/topics/{id}

Delete a topic. Existing contact subscriptions for this topic will be removed.

Subscribe contacts to a topic

POST
/v1/topics/{id}/contacts

Subscribe one or more contacts to a topic. Reactivates opted-out subscriptions.

Request body

ParameterTypeDescription
contactIdsrequiredstring[]Array of contact IDs to subscribe.
cURL
curl -X POST https://api.txtly.com.au/v1/topics/d290f1ee-.../contacts \
  -H "Authorization: Bearer tx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"contactIds": ["a1b2c3d4-5e6f-7890-abcd-ef1234567890"]}'
Example Response
{
  "added": 1,
  "reactivated": 0,
  "alreadySubscribed": 0
}

Unsubscribe a contact from a topic

DELETE
/v1/topics/{id}/contacts/{contactId}

Unsubscribe a contact from a topic by setting their status to opt-out.

Contact subscriptions

Each contact-topic relationship has a status of eitheropt_inoropt_out. Broadcasts scoped to a topic will only be sent to contacts withopt_instatus. Unsubscribing sets the status to opt_out rather than deleting the record, preserving the opt-out preference.