# Enviar un SMS (/es/api-reference/public-api/sendSms)

`POST /v1/sms/send`

Base URL: `https://api.bitelio.com`

Envía un SMS transaccional. Refleja `POST /v1/send`: clave secreta con el permiso `sms:send`, y cabecera `Idempotency-Key` si quieres que un reintento sea seguro.

**El remitente no lo eliges tú.** Se resuelve a partir del país del destinatario y de los remitentes que tu proyecto tenga registrados, porque lo que es un remitente válido cambia según el país — un ID alfanumérico sirve en España y se rechaza en Estados Unidos.

**Se paga por segmentos, no por mensajes.** Un mensaje GSM-7 se parte cada 160 caracteres; uno Unicode, cada 70. La respuesta te dice en cuántos se convirtió antes de que se te facturen.

Devuelve **202**: aceptado para entrega, no entregado. El estado llega por webhook.

## Header parameters

- `Idempotency-Key`: string

## Request body

- `to`: string (required) — Destino en formato E.164, p. ej. `+34600000000`.
- `body`: string (required) — Texto del mensaje. Hasta 1600 caracteres; un cuerpo más largo se rechaza, no se recorta.
- `contactId`: string (uuid) — Asocia el mensaje a un contacto que ya tienes, en vez de emparejar por número.

Example:

```json
{
  "to": "+34600000000",
  "body": "string"
}
```

## Responses

### `202` — Aceptado para entrega

- `id`: string
- `to`: string
- `from`: string
- `country`: string
- `encoding`: enum ("GSM7" | "UCS2")
- `segments`: integer
- `status`: string

```json
{
  "id": "string",
  "to": "string",
  "from": "string",
  "country": "string",
  "encoding": "GSM7",
  "segments": 0,
  "status": "string"
}
```

### `400` — El cuerpo no pasó la validación

### `403` — La clave no tiene el permiso sms:send, o el canal SMS no está habilitado

### `409` — Esa Idempotency-Key ya la usó este proyecto

## Example request

```bash
curl -X POST 'https://api.bitelio.com/v1/sms/send' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"to":"+34600000000","body":"string"}'
```