---
title: "Send an SMS/MMS"
method: POST
path: "/v1/sms/messages"
tags: ["SMS"]
---

# Send an SMS/MMS

`POST /v1/sms/messages`

Sends an SMS (or MMS when `mediaUrls` is set) from one of your
SMS-enabled numbers. At least one of `text` / `mediaUrls` is required.
Both numbers are normalized to E.164, so `from` matches regardless of
formatting and replies thread into the same inbox conversation.

US numbers must have an approved carrier registration
(`/v1/sms/registrations`) before messages deliver.

**Idempotency:** send an `Idempotency-Key` header to make retries safe:
same key + same body replays the original response instead of sending a
second message; same key + different body returns 422; a key still in
flight returns 409.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `from` string, required — One of your SMS-enabled numbers (E.164; formatting is normalized).
  - `to` string, required — Recipient number (E.164).
  - `text` string — Message body. Required unless `mediaUrls` is set. Max 10 SMS segments (1530 GSM-7 or 670 unicode characters).
  - `mediaUrls` string[] — Public media URLs to attach (sends as MMS). Max 10.
  - `sendAt` string, date-time — Optional. Schedule the send for a future time (ISO 8601 with offset, e.g. `2026-08-01T12:00:00Z`). Must be in the future. The message is queued and the `message.delivered` webhook fires when it actually sends.

## Response `200`

Message accepted for delivery.

- object
  - `id` string — Message ID
  - `conversationId` string — Inbox conversation the message was threaded into.
  - `status` 'sent'

## Other responses

- `401` — Unauthorized
- `404` — No SMS-enabled number matches `from`
- `409` — Same Idempotency-Key still processing; retry after a short backoff
- `422` — Idempotency-Key reused with a different body
- `502` — Carrier-side send failed

---

[API](https://skmtc.net/zernio/apis/zernio-api.md) · [All operations](https://skmtc.net/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zernio/zernio-api/versions/f81ca70ea6b9/schema)