---
title: "Send an SMS message"
method: POST
path: "/v1/messages"
---

# Send an SMS message

`POST /v1/messages`

## Request

- Base URL: `https://volai.cz`
- URL: `https://volai.cz/v1/messages`
- Auth: HTTP bearer

Sends an SMS. Czech and Slovak numbers only (`+420` / `+421`). Price is 1.36 CZK per **segment** - longer messages (or ones with characters outside the GSM-7 alphabet, typically Czech diacritics) split into more segments, each billed separately - see `segments` in the response. Requires a first credit top-up - the welcome credit does not unlock SMS. To send from your own SMS number, set `fromNumber` (a number from `GET /v1/sms-numbers`). The recipient then sees your number instead of SMSinfo. Sending from the number works only to Czech numbers (`+420`), costs 1.90 CZK per segment (excluding VAT) and has a daily cap per account: 20 messages in the first 30 days after you buy the number, 50 after that. The `from` field in the request is still ignored.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `to` string, required: SMS destination with Czech +420 or Slovak +421 country code, normalized to E.164. Sending from an SMS number (fromNumber) accepts only +420.
  - `body` string, required: Message text. Under the shared sender, include your name or brand in the text. Billed per GSM-7 or Unicode segment. Carrier acceptance is not a delivery receipt.
  - `fromNumber` string: Optional active SMS number of your account in E.164, from GET /v1/sms-numbers, to send from instead of the shared sender SMSinfo. Billed per segment at the SMS number rate. Omit it, or send an empty string, to use the shared sender.

## Response `200`

Sent message

- object
  - `id` string, required
  - `status` 'pending' | 'sent' | 'failed' | 'unknown', required
  - `priceHal` number, required
  - `segments` number

## Other responses

- `400`: Error codes: validation (request), invalid_number (request), invalid_body (request), unsupported_country (request), blocked_destination (request), recipient_cannot_receive_sms (request), unsupported_characters (request), recipient_is_virtual_number (request), recipient_rejected (request), invalid_from_number (request), from_number_unsupported_destination (request).
- `401`: Error codes: unauthorized (request).
- `402`: Error codes: insufficient_credit (account), subscription_cap_reached (account).
- `403`: Error codes: account_suspended (account), sms_numbers_unavailable (account).
- `409`: Error codes: idempotency_in_progress (busy), recipient_opted_out (request).
- `429`: Error codes: rate_limited (busy).
- `500`: Error codes: internal_error (service).
- `502`: Error codes: send_failed (service), send_failed_operator (service), sms_gateway_failed (service), send_unknown (service).
- `503`: Error codes: ledger_unavailable (service).

---

[API](https://skmtc.dev/volai/apis/volai-rest-api.md) · [All operations](https://skmtc.dev/volai/apis/volai-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/volai/apis/volai-rest-api/revisions/12029b05e2fa?raw)