---
title: "SMS"
description: "Beta. Send transactional and marketing SMS, and track each message's delivery lifecycle. Marketing sends require recipient consent and honor recipient-local quiet hours. Returns `not_found` on workspaces where the channel isn't enabled yet."
url: https://www.unitpost.com/docs/api/sms
section: API reference
updated: 2026-07-31
---
# SMS

## SMS

> Beta. Send transactional and marketing SMS, and track each message's delivery lifecycle. Marketing sends require recipient consent and honor recipient-local quiet hours. Returns `not_found` on workspaces where the channel isn't enabled yet.

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

## Operations

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

List SMS messages

Retrieve your workspace's SMS messages (outbound and inbound), newest-first and cursor-paginated. Use a message's `id` with [Retrieve an SMS message](#get-sms-id) to read its delivery state. Requires the `sms:read` capability.

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

Send an SMS message

Send a single SMS — now, or at a future time by passing `scheduled_at`. The recipient must be a valid E.164 number; marketing sends additionally require the recipient's prior express consent on record and honor recipient-local quiet hours (they are deferred to the next allowed window, never dropped). Billing is per segment. Read delivery state back with [Retrieve an SMS message](#get-sms-id). Requires the `sms:send` capability.

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

Retrieve an SMS message

Retrieve one SMS message's current status, delivery state, and segment count by `id`. Requires the `sms:read` capability.

## 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.