API массовой рассылки SMS v1

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

Создайте ключ в консоли в разделе API и вебхуки; ключи становятся доступны после первого пополнения баланса. Отправляйте его в каждом запросе как Bearer-токен. Ключ показывается один раз; вы можете хранить до 5 ключей и отозвать любой из них в любой момент.

Authorization: Bearer smsb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Тарифы

Публичный, ключ не требуется. Цена за сегмент SMS для каждого направления или для одного кода ISO.

GEThttps://smsbulk.cc/rest/v1/rates

GEThttps://smsbulk.cc/rest/v1/rates/{ISO}

{
  "country": "US",
  "name": "United States",
  "dial_code": "+1",
  "rate": "0.00485",
  "currency": "USD",
  "per": "message segment"
}

Баланс

GEThttps://smsbulk.cc/rest/v1/credit

{ "credit": "125.40000", "currency": "USD", "account": "A418820037715" }

Расчет

Рассчитывает стоимость отправки без фактической отправки. Принимает те же данные, что и Send.

POSThttps://smsbulk.cc/rest/v1/quote

{
  "recipients": 2,
  "messages": 2,
  "segments": { "min": 1, "max": 1 },
  "encoding": "GSM-7",
  "total": "0.01240",
  "currency": "USD",
  "credit": "125.40000",
  "credit_after": "125.38760",
  "countries": [
    { "country": "US", "recipients": 1, "rate": "0.00485", "segments": 1, "subtotal": "0.00485" },
    { "country": "GB", "recipients": 1, "rate": "0.00755", "segments": 1, "subtotal": "0.00755" }
  ],
  "left_out": []
}

Отправка

Создает кампанию, списывает общую сумму с вашего баланса и ставит сообщения в очередь. Возвращает код 201 с данными кампании. Номера, которые нельзя отправить, перечислены в left_out и не списываются.

POSThttps://smsbulk.cc/rest/v1/send

HTTP/1.1 201 Created
{
  "campaign": {
    "id": "C507318264409",
    "name": null,
    "status": "sending",
    "source": "api",
    "test": false,
    "recipients": 2,
    "cost": "0.01240",
    "refunded": "0.00000",
    "net_cost": "0.01240",
    "currency": "USD",
    "send_at": null,
    "created_at": "2026-11-07T14:02:11.000Z",
    "started_at": "2026-11-07T14:02:11.000Z",
    "finished_at": null,
    "client_ref": "order-batch-17"
  },
  "messages": 2,
  "left_out": []
}

Кампании

GEThttps://smsbulk.cc/rest/v1/campaigns?limit=25&before={id}

GEThttps://smsbulk.cc/rest/v1/campaigns/{id}

GEThttps://smsbulk.cc/rest/v1/campaigns/{id}/messages?status=failed&limit=100&after={message id}

Одна кампания включает количество сообщений по статусам: в очереди, отправлено, доставлено, не доставлено и отменено. Списки сообщений страничные с параметрами after и has_more; до 1,000 на странице.

Сообщения

GEThttps://smsbulk.cc/rest/v1/messages/{id}

GEThttps://smsbulk.cc/rest/v1/messages?to=%2B14155550142&status=delivered&client_ref=order-batch-17&limit=50

{
  "id": "M220947781305",
  "campaign": "C507318264409",
  "to": "+14155550142",
  "country": "US",
  "segments": 1,
  "encoding": "GSM-7",
  "price": "0.00485",
  "status": "delivered",
  "reason": null,
  "reason_text": null,
  "refunded": false,
  "client_ref": "order-batch-17",
  "created_at": "2026-11-07T14:02:11.000Z",
  "sent_at": "2026-11-07T14:02:12.000Z",
  "finished_at": "2026-11-07T14:02:16.000Z"
}

Отменить запланированную кампанию

POSThttps://smsbulk.cc/rest/v1/campaigns/{id}/cancel

Работает до времени начала. Вся стоимость возвращается на ваш баланс одной строкой в журнале, а статус кампании становится отмененным.

Вебхуки

Укажите URL конечной точки в консоли. Мы отправляем POST JSON для message.delivered, message.failed и campaign.done, а также тестовый запрос при нажатии Send test event. Каждое событие содержит четыре заголовка, и любой ответ 2xx в течение 10 секунд считается полученным.

Доставка пробуется 8 раз: сразу, затем через 1 минуту, 5 минут, 15 минут, 1 час, 3 часа, 6 часов и 12 часов. Каждая попытка отображается в журнале доставки в консоли с ее HTTP-статусом и началом вашего ответа.

{
  "id": "dlv_3f9a1c07b2e44d58a6c1",
  "event": "message.failed",
  "created": "2026-11-07T14:02:16.000Z",
  "data": {
    "message": "M220947781305",
    "campaign": "C507318264409",
    "to": "+447400123456",
    "country": "GB",
    "status": "failed",
    "reason": "not_in_service",
    "segments": 1,
    "price": "0.00755",
    "client_ref": "order-batch-17"
  }
}

Проверить подпись

import crypto from "node:crypto";

// raw = the request body exactly as received (string), secret = your sbw_ signing secret
export function verify(raw, headers, secret) {
  const ts = headers["smsbulk-timestamp"];
  const want = "sha256=" + crypto.createHmac("sha256", secret).update(ts + "\n" + raw).digest("base64");
  const got = headers["smsbulk-signature"] || "";
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  return fresh && got.length === want.length && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(want));
}

import base64, hashlib, hmac, time

def verify(raw: bytes, headers, secret: str) -> bool:
    ts = headers.get("Smsbulk-Timestamp", "")
    mac = hmac.new(secret.encode(), ts.encode() + b"\n" + raw, hashlib.sha256).digest()
    want = "sha256=" + base64.b64encode(mac).decode()
    fresh = abs(time.time() - int(ts or 0)) < 300
    return fresh and hmac.compare_digest(want, headers.get("Smsbulk-Signature", ""))

Ошибки и ограничения

Ошибки используют HTTP-статус и тело JSON: {"error":{"code":"insufficient_credit","message":"..."}}. Ничего не списывается при неудачном запросе.

Каждый ответ содержит X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset.

Исключенные коды

Номера, удалённые перед расчётом стоимости, возвращаются в left_out с их позицией в вашем списке, значением, которое вы отправили, кодом и простой причиной.

Статусы и причины

Вопросы по API? Откройте тикет в консоли или прочитайте FAQ.