API masowych SMS v1

Uwierzytelnianie

Utwórz klucz w konsoli w sekcji API i webhooki; klucze stają się dostępne po pierwszym doładowaniu środków. Wysyłaj go w każdym żądaniu jako token Bearer. Klucz jest pokazywany tylko raz; możesz przechowywać do 5 kluczy i odwołać dowolny z nich w dowolnym momencie.

Authorization: Bearer smsb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Ceny

Publiczne, nie wymaga klucza. Cena za segment SMS dla każdego celu lub dla jednego kodu 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"
}

Środki

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

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

Wycenia

Wycenia wysyłkę bez jej wysyłania. Przyjmuje tę samą treść co 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": []
}

Wyślij

Tworzy kampanię, pobiera jej całkowity koszt z Twoich środków i kolejkowuje wiadomości. Odpowiada kodem 201 z kampanią. Numery, których nie można wysłać, są wymienione w left_out i nigdy nie są naliczane.

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": []
}

Kampanie

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}

Pojedyncza kampania zawiera liczniki według statusów: w kolejce, wysłane, dostarczone, nieudane i anulowane. Listy wiadomości stronicowane z after i has_more; do 1,000 na stronę.

Wiadomości

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"
}

Anuluj zaplanowaną kampanię

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

Działa do czasu rozpoczęcia. Cały koszt wraca do Twoich środków w jednej linii księgowej, a status kampanii zmienia się na anulowany.

Webhooki

Ustaw URL endpointu w konsoli. Wysyłamy POST JSON dla message.delivered, message.failed i campaign.done, plus test po naciśnięciu Wyślij testowe zdarzenie. Każde zdarzenie zawiera cztery nagłówki, a każda odpowiedź 2xx w ciągu 10 sekund jest uznawana za otrzymaną.

Dostarczenie jest próbowane 8 razy: natychmiast, a następnie po 1 minucie, 5 minutach, 15 minutach, 1 godzinie, 3 godzinach, 6 godzinach i 12 godzinach. Każda próba jest pokazywana w dzienniku dostarczenia konsoli z jej statusem HTTP i początkiem Twojej odpowiedzi.

{
  "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"
  }
}

Zweryfikuj podpis

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", ""))

Błędy i limity

Błędy wykorzystują status HTTP i treść JSON: {"error":{"code":"insufficient_credit","message":"..."}}. Nic nie jest naliczane, gdy żądanie nie powiedzie się.

Każda odpowiedź zawiera X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset.

Pominięte kody

Numery usunięte przed wyceną wracają w left_out z ich pozycją na liście, wartością, którą wysłałeś, kodem i prostym powodem.

Statusy i powody

Pytania dotyczące API? Otwórz zgłoszenie w konsoli lub przeczytaj FAQ.