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 кінцевої точки в консолі. Ми надсилаємо JSON для message.delivered, message.failed та campaign.done, а також тест, коли ви натискаєте Надіслати тестову подію. Кожна подія містить чотири заголовки, і будь-яка відповідь 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.