# Send an SMS (/api-reference/public-api/sendSms)

`POST /v1/sms/send`

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

Send a single transactional SMS. Mirrors `POST /v1/send`: a secret key with the `sms:send` scope, and an `Idempotency-Key` header if you want a retry to be safe.

**You do not choose the sender.** It is resolved from the destination's country and the senders your project has registered, because what counts as a valid sender differs per country — an alphanumeric sender ID works in Spain and is rejected in the United States.

**Segments, not messages, are what you pay for.** A GSM-7 message splits every 160 characters, a Unicode one every 70. The response tells you how many this became before you are billed for them.

Returns **202**: accepted for delivery, not delivered. Delivery status arrives by webhook.

## Header parameters

- `Idempotency-Key`: string

## Request body

- `to`: string (required) — Destination in E.164 form, e.g. `+34600000000`.
- `body`: string (required) — Message text. Up to 1600 characters; longer bodies are refused rather than truncated.
- `contactId`: string (uuid) — Attach the message to a contact you already have, instead of matching by number.

Example:

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

## Responses

### `202` — Accepted for delivery

- `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` — The body failed validation

### `403` — The key lacks the sms:send scope, or SMS is not enabled for this deployment

### `409` — This Idempotency-Key was already used by this project

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