Шесть конечных точек.
Документировано каждое поле.

Соглашения

Запросы принимают application/json или данные формы; ответы всегда возвращаются в JSON. Метки времени имеют формат ISO 8601 и часовой пояс UTC. Денежные суммы передаются строкой в USD с четырьмя знаками после точки. Номера телефонов имеют формат E.164 с начальным плюсом. Идентификаторы используют префиксы msg_, bat_, evt_, cmp_. Каждый ответ содержит X-Request-Id; укажите его при обращении в поддержку.

Аутентификация

Authorization: Bearer sk_live_9f2c...a71e

Области доступа: send (создание сообщений), read (все запросы GET). Для ключа можно задать список разрешённых IP-адресов; запросы с других адресов получают 401 unauthorized. Тестовые ключи (sk_test_) работают так же, но не отправляют сообщения и не списывают средства.

Идемпотентность

Любой POST принимает Idempotency-Key — выбранную вами строку длиной до 128 символов. При одинаковом ключе и теле в течение 24 часов возвращается исходный ответ с заголовком Idempotent-Replayed: true. Тот же ключ с другим телом возвращает 409 idempotency_conflict.

Создать сообщение

POST/v1/messages

POST /v1/messages
Authorization: Bearer sk_live_...
Idempotency-Key: order-4821-ship
Content-Type: application/json

{
  "to": "+14155550142",
  "from": "METEOR",
  "text": "Ваш заказ №4821 отправлен. Отслеживание: smsmtr.io/t/8fK2",
  "campaign": "shipping",
  "reference": "order-4821"
}

{
  "id": "msg_9Kd2fQ",
  "status": "queued",
  "to": "+14155550142",
  "from": "METEOR",
  "text": "Ваш заказ №4821 отправлен. Отслеживание: smsmtr.io/t/8fK2",
  "segments": 1,
  "encoding": "gsm7",
  "price": "0.0084",
  "currency": "USD",
  "country": "us",
  "campaign": "shipping",
  "reference": "order-4821",
  "created_at": "2026-09-21T11:42:07Z",
  "sent_at": null,
  "delivered_at": null,
  "carrier_code": null
}

Создать пакет

POST/v1/messages/batch

До 1000 сообщений в одном запросе API сообщений, у каждого свои to, text и необязательные from, reference. Значения верхнего уровня from, campaign, send_at, window и pace применяются ко всем сообщениям, где они не переопределены. По синтаксису пакет принимается или отклоняется целиком; отдельные сообщения всё равно могут быть отклонены из-за направления или содержимого и перечисляются с причиной.

{
  "batch_id": "bat_3Hq9Zr",
  "accepted": 2, "rejected": 1,
  "total_price": "0.0214", "currency": "USD",
  "messages": [
    { "id": "msg_9Kd2fQ", "to": "+14155550142", "status": "queued", "price": "0.0084" },
    { "id": "msg_9Kd2fR", "to": "+447700900123", "status": "queued", "price": "0.0130" },
    { "to": "+99912345", "status": "rejected", "error": { "code": "unsupported_destination" } }
  ]
}

Параметры планирования

Три способа задать время отправки для отдельных сообщений и пакетов. Их можно сочетать: для рекламных рассылок обычно используют window вместе с pace.

Получить сообщение

GET/v1/messages/{id}

Возвращает объект сообщения Message с текущим статусом, метками времени, ценой и кодом оператора связи при ошибке.

Список сообщений

GET/v1/messages

{ "data": [ { "id": "msg_9Kd2fQ", "status": "delivered", "...": "..." } ],
  "next_cursor": "eyJpZCI6Im1zZ185S2QyZlEifQ", "has_more": true }

Тарифы

GET/v1/ratesиGET/v1/rates/{iso}

Публичная таблица тарифов, идентичная странице тарифов. Каждая запись содержит направление, телефонный код, цену за сегмент, правило имени отправителя и ограничения по времени отправки. Ответ можно кешировать на час; тарифы меняются не чаще раза в день. Ключ не требуется.

{ "country": "gb", "name": "United Kingdom", "dial": "44",
  "price": "0.0130", "currency": "USD",
  "sender": "alphanumeric", "quiet_hours": { "start": "08:00", "end": "21:00" },
  "updated_at": "2026-09-21" }

Баланс

GET/v1/balance

{ "balance": "1240.60", "currency": "USD", "pending": "0.00",
  "low_threshold": "100.00", "updated_at": "2026-09-21T11:40:00Z" }

Объект сообщения Message

Статусы

1. В очередиПринято и оценено, ожидает места в маршруте.
2. ОтправленоПередано оператору связи. В этот момент списываются средства.
3. ДоставленоУстройство подтвердило получение. Конечный статус.
4. ОшибкаОператор связи не смог доставить; указано carrier_code. Конечный статус.
5. Срок истёкСрок действия истёк без доставки. Конечный статус.
6. ОтклоненоОтклонено до отправки. Средства не списываются. Конечный статус.

Ошибки

{ "error": { "code": "insufficient_balance", "message": "Balance 0.42 USD is below the message price 0.85 USD", "field": null } }

Ограничения частоты

50 запросов в секунду на ключ, измеряется в скользящем окне. Каждый пакетный запрос считается одним запросом. Ответы содержат X-RateLimit-Limit, X-RateLimit-Remaining, а при 429 — Retry-After в секундах.

Журнал изменений

• 2026-09 Поле window.quiet_hours принимает значение bypass для транзакционного трафика.
• 2026-07 В пакетных ответах отклонённые элементы перечисляются вместе с ошибками, а весь пакет не считается ошибочным.
• 2026-06 Поле reference добавлено в вебхуки.
• 2026-04 Добавлен GET /v1/rates/{iso}.