---
title: "Cancel or reschedule an SMS"
method: PATCH
path: "/sms/{id}"
tags: ["SMS"]
---

# Cancel or reschedule an SMS

`PATCH /sms/{id}`

## Request

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

Cancel a `scheduled` or `queued` SMS (its reserved credit is refunded), or move a `scheduled` one to a new send time with `scheduled_at`. Send exactly one of `cancel: true` or `scheduled_at`. Only a text the carrier has not been handed can be changed — afterwards this returns `409`, as it does for a text that belongs to a campaign. Quiet hours still apply to the new time. Look up the current state first with [Retrieve an SMS message](#get-sms-id). Requires the `sms:send` capability.

## Path parameters

- `id` string, required

## Request body

- SmsPatch
  - `cancel` true: Cancel a `queued` or `scheduled` text. Its reserved credit is refunded.
  - `scheduled_at` string, date-time: Move a `scheduled` text to this future ISO-8601 time.

## Response `200`

The updated 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.
- `409`: The text is not in a cancelable / reschedulable state.
- `422`: Validation error.
- `502`: The new time couldn't be handed to the delivery engine; the text keeps its original time.

---

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