> ## 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.

# Enviar un SMS

> Enviar un mensaje SMS global y rastrear su estado de entrega final.

## Qué es

La API de SMS envía un mensaje de texto a un número de teléfono. Úsela para notificaciones,
alertas, actualizaciones transaccionales y otras comunicaciones basadas en texto.

## Antes de empezar

* Guarde su clave de API de YCloud en `YCLOUD_API_KEY`.
* Aplique el formato E.164 al número del destinatario.
* Registre un `senderId` aprobado cuando el destino lo requiera.
* Proporcione un `signature` aprobado para los mensajes enviados a China continental.

## Cómo funciona

Envía el mensaje con `POST /sms`. Una respuesta exitosa significa que YCloud aceptó
la solicitud. No garantiza la entrega final.

YCloud actualiza el mensaje de `accepted` a un estado posterior como `sent`,
`delivered`, `undelivered` o `failed`. Recibe estos cambios a través del
Webhook de `sms.message.updated` o recupera los registros de SMS con `GET /sms`.

## Solicitud

`POST /sms`

### Campos de solicitud

| Campo | Obligatorio | Descripción |
| - | - | - |
| `to` | Sí | Número de teléfono del destinatario en formato E.164. |
| `text` | Sí | Cuerpo del mensaje de texto. |
| `senderId` | No | ID de remitente aprobado utilizado para el mensaje. La disponibilidad varía según el destino. |
| `signature` | Condicional | Firma aprobada para China continental. YCloud la envuelve en `【】` y la antepone al mensaje. |
| `externalId` | No | Su referencia única para conciliar el mensaje con un registro interno. |
| `callbackUrl` | No | URL de informe de entrega por mensaje. Utilice puntos de enlace de Webhook para nuevas integraciones. |

### Ejemplo de solicitud

```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"
  }'
```

## Respuesta

Una respuesta exitosa devuelve el objeto SMS creado. Guarde su `id` para
correlacionar las actualizaciones de entrega y recuperar el mensaje más tarde.

### Ejemplo de respuesta

```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"
}
```

### Campos de respuesta

| Campo | Descripción |
| - | - |
| `id` | ID del mensaje de YCloud. Guárdelo para su recuperación y correlación de eventos. |
| `status` | Estado de entrega actual. `accepted` significa que la solicitud fue aceptada, no entregada. |
| `totalSegments` | Número de segmentos de SMS utilizados por el mensaje. |
| `totalPrice` | Precio total del mensaje cuando esté disponible. |
| `currency` | Moneda del precio en formato ISO 4217. |
| `errorCode` | Código de error cuando el mensaje no se puede entregar. |
| `createTime` | Hora de creación del mensaje en formato RFC 3339. |
| `updateTime` | Hora de la última actualización del estado de entrega. |
| `externalId` | La referencia proporcionada en la solicitud. |

## Estado de entrega

Suscríbase a `sms.message.updated` para los cambios de estado de salida. Suscríbase a
`sms.inbound.received` si su cuenta recibe respuestas de SMS.

Utilice `GET /sms` para conciliar los registros por hora de creación o ID de mensaje.

## Límites y solución de problemas

* La disponibilidad del ID del remitente y las reglas de contenido varían según el destino.
* Los mensajes largos pueden usar múltiples segmentos de SMS y costar más.
* No vuelva a intentar una solicitud aceptada sin una estrategia de idempotencia. Una solicitud
  repetida puede enviar un mensaje duplicado.
* Utilice `id` y `externalId` devueltos cuando investigue un problema de entrega.


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