---
title: "Retrieve an SMS message"
method: GET
path: "/sms/{id}"
tags: ["SMS"]
---

# Retrieve an SMS message

`GET /sms/{id}`

## Request

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

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

## Path parameters

- `id` string, required

## Response `200`

The SMS message.

- Sms
  - `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.
- `404`: Message not found.

---

[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)