> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send an SMS

> Send a global SMS message and track its final delivery status.

## What it is

The SMS API sends a text message to one phone number. Use it for notifications,
alerts, transactional updates, and other text-based communication.

## Before you begin

* Store your YCloud API key in `YCLOUD_API_KEY`.
* Format the recipient number in E.164 format.
* Register an approved `senderId` when the destination requires one.
* Provide an approved `signature` for messages sent to mainland China.

## How it works

Send the message with `POST /sms`. A successful response means YCloud accepted
the request. It does not guarantee final delivery.

YCloud updates the message from `accepted` to a later status such as `sent`,
`delivered`, `undelivered`, or `failed`. Receive these changes through the
`sms.message.updated` Webhook or retrieve SMS records with `GET /sms`.

## Request

`POST /sms`

### Request fields

| Field | Required | Description |
| - | - | - |
| `to` | Yes | Recipient phone number in E.164 format. |
| `text` | Yes | Text message body. |
| `senderId` | No | Approved Sender ID used for the message. Availability varies by destination. |
| `signature` | Conditional | Approved signature for mainland China. YCloud wraps it in `【】` and prepends it to the message. |
| `externalId` | No | Your unique reference for reconciling the message with an internal record. |
| `callbackUrl` | No | Per-message delivery report URL. Use Webhook endpoints for new integrations. |

### Example request

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST https://api.ycloud.com/v2/sms \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "to": "+16315551111",
    "text": "Your verification code is 123456.",
    "externalId": "login-10001"
  }'
```

## Response

A successful response returns the created SMS object. Store its `id` to
correlate delivery updates and retrieve the message later.

### Example response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "to": "+16315551111",
  "text": "Your verification code is 123456.",
  "regionCode": "US",
  "totalSegments": 1,
  "status": "accepted",
  "externalId": "login-10001",
  "createTime": "2026-07-16T12:00:00.000Z"
}
```

### Response fields

| Field | Description |
| - | - |
| `id` | YCloud message ID. Store it for retrieval and event correlation. |
| `status` | Current delivery state. `accepted` means the request was accepted, not delivered. |
| `totalSegments` | Number of SMS segments used by the message. |
| `totalPrice` | Total message price when available. |
| `currency` | ISO 4217 price currency. |
| `errorCode` | Failure code when the message is undeliverable. |
| `createTime` | Message creation time in RFC 3339 format. |
| `updateTime` | Time of the latest delivery status update. |
| `externalId` | The reference supplied in the request. |

## Delivery status

Subscribe to `sms.message.updated` for outbound status changes. Subscribe to
`sms.inbound.received` if your account receives SMS replies.

Use `GET /sms` to reconcile records by creation time or message ID.

## Limits and troubleshooting

* Sender ID availability and content rules vary by destination.
* Long messages may use multiple SMS segments and cost more.
* Do not retry an accepted request without an idempotency strategy. A repeated
  request can send a duplicate message.
* Use the returned `id` and `externalId` when investigating a delivery issue.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.