---
title: "List SMS messages"
method: GET
path: "/sms"
tags: ["SMS"]
---

# List SMS messages

`GET /sms`

## Request

- Base URL: `https://www.unitpost.com/api/v1`
- URL: `https://www.unitpost.com/api/v1/sms`
- Auth: HTTP bearer

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.

## Query parameters

- `limit` integer
- `after` string
- `before` string

## Response `200`

A page of SMS messages.

- object
  - `object` 'list', required
  - `has_more` boolean, required
  - `data` Sms[], required
    - `object` 'sms', required
    - `id` string, required
    - `to` string, required
    - `from` string, nullable, required
    - `direction` 'outbound' | 'inbound', required
    - `status` 'queued' | 'scheduled' | 'sending' | 'sent' | 'delivered' | 'failed' | 'suppressed' | 'canceled' | 'received', required
    - `type` 'transactional' | 'marketing', required
    - `body` string, nullable, required
    - `segments` integer, required
    - `country` string, nullable, required
    - `scheduled_at` string, nullable, required
    - `last_error` string, nullable, required: Legacy free-text error. Prefer `error.code`.
    - `error` object, nullable, required: Set on `suppressed` messages: the stable skip reason and its sentence. Null otherwise.
      - `code` 'out_of_reach' | 'unsupported_country' | 'no_phone' | 'opted_out' | 'no_marketing_consent' | 'quiet_hours_deferred' | 'sender_not_active', required: Why a message was skipped before reaching the carrier. `out_of_reach`: no sender covers the recipient's country; `unsupported_country`: no compliance rule for the country yet; `no_phone`: the contact has no SMS handle; `opted_out`: STOP / suppression / unreachable; `no_marketing_consent`: marketing without express consent; `quiet_hours_deferred`: delayed to the recipient's local window; `sender_not_active`: the sender lost approval.
      - `message` string, required: Human-readable sentence for `code`.
    - `created_at` string, required

## Other responses

- `401`: Missing or invalid API key.
- `403`: Insufficient scope.
- `422`: Invalid pagination params.

---

[API](https://skmtc.dev/unitpost/apis/unitpost-api.md) · [All operations](https://skmtc.dev/unitpost/apis/unitpost-api/llms.txt) · [OpenAPI document](https://skmtc.dev/unitpost/apis/unitpost-api/revisions/86ff7c890967?raw)