---
title: "SMS topics"
description: "SMS subscription categories recipients can opt out of, independent from email topics. STOP still opts a number out of every SMS."
url: https://www.unitpost.com/docs/api/sms-topics
section: API reference
updated: 2026-10-13
---
# SMS topics

## SMS topics

> SMS subscription categories recipients can opt out of, independent from email topics. STOP still opts a number out of every SMS.

Full schemas: [OpenAPI 3.1](https://www.unitpost.com/api/v1/openapi.json). HTML reference: https://www.unitpost.com/docs/sms#sms-topics.

## Operations

### `GET /api/v1/sms/topics`

List SMS topics

Retrieve your SMS subscription topics, cursor-paginated. An SMS topic is a category of marketing SMS (e.g. Flash sales) recipients can opt out of while still receiving your other texts. SMS and email topics are separate: a contact's email preference never changes their SMS one, and STOP still opts a number out of every SMS. Pass `?archived=true` to list archived topics instead. Create one with [Create an SMS topic](https://www.unitpost.com/docs/sms/post-sms-topics). Requires the `topics:read` capability.

Reference: https://www.unitpost.com/docs/sms/get-sms-topics ([Markdown](https://www.unitpost.com/docs/sms/get-sms-topics.md))

### `POST /api/v1/sms/topics`

Create an SMS topic

Create an SMS subscription topic. `default_opt_in` decides whether contacts with no explicit preference are treated as subscribed. Names are unique per channel, so an SMS topic may share a name with an email topic. Topics are a plan feature: an unentitled workspace gets `403` with `limit_reached`. Requires the `topics:write` capability.

Reference: https://www.unitpost.com/docs/sms/post-sms-topics ([Markdown](https://www.unitpost.com/docs/sms/post-sms-topics.md))

### `GET /api/v1/sms/topics/{id}`

Retrieve an SMS topic

Retrieve a single SMS topic by `id`. An email topic id returns `404` here. Change it with [Update an SMS topic](https://www.unitpost.com/docs/sms/patch-sms-topics-id). Requires the `topics:read` capability.

Reference: https://www.unitpost.com/docs/sms/get-sms-topics-id ([Markdown](https://www.unitpost.com/docs/sms/get-sms-topics-id.md))

### `PATCH /api/v1/sms/topics/{id}`

Update an SMS topic

Update an SMS topic's name, description or `default_opt_in`, or pass `{ "archived": true | false }` to archive or restore it. Archiving is blocked with `409` while an active SMS campaign or a live automation still uses the topic. Requires the `topics:write` capability.

Reference: https://www.unitpost.com/docs/sms/patch-sms-topics-id ([Markdown](https://www.unitpost.com/docs/sms/patch-sms-topics-id.md))

### `DELETE /api/v1/sms/topics/{id}`

Delete an SMS topic

Archive an SMS topic (a soft delete: subscription records are kept so you can restore it with `{ "archived": false }` on [Update an SMS topic](https://www.unitpost.com/docs/sms/patch-sms-topics-id)). Blocked with `409` while an active SMS campaign or a live automation still uses it. Requires the `topics:write` capability.

Reference: https://www.unitpost.com/docs/sms/delete-sms-topics-id ([Markdown](https://www.unitpost.com/docs/sms/delete-sms-topics-id.md))

## Related

- [API keys](https://www.unitpost.com/docs/api/api-keys): Create and revoke the API keys your integrations authenticate with. These endpoints are session-gated (dashboard cookie + `apikeys:manage`) and NOT usable with a Bearer API key.
- [Suppressions](https://www.unitpost.com/docs/api/suppressions): Address-level send blocks — the hard "never email this address" list. Combines engine-written bounce/complaint entries, your own additions, and read-only Unitpost-wide blocks.
- [Usage](https://www.unitpost.com/docs/api/usage): Your workspace's current billing-period usage: emails sent, and on paid plans the dollar sending wallet (monthly allowance, spend, purchased credit, overage) in integer USD cents.