Send an SMS

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

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

{
  "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.

Getting Started

Guides

Endpoints

Webhooks

What it is

Before you begin

How it works

Request

Request fields

Example request

Response

Example response

Response fields

Delivery status

Limits and troubleshooting

​What it is

​Before you begin

​How it works

​Request

​Request fields

​Example request

​Response

​Example response

​Response fields

​Delivery status

​Limits and troubleshooting

What it is

Before you begin

How it works

Request

Request fields

Example request

Response

Example response

Response fields

Delivery status

Limits and troubleshooting