Toplu SMS API v1

Kimlik Doğrulama

Konsolda API ve webhooklar altında bir anahtar oluşturun; anahtarlar ilk kredili yüklemenizden sonra açılır. Her istekte Bearer token olarak gönderin. Bir anahtar bir kez gösterilir; en fazla 5 anahtar tutabilir ve herhangi birini anında iptal edebilirsiniz.

Authorization: Bearer smsb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Fiyatlar

Herkese açık, anahtar gerekmez. Her hedef için SMS segmenti başına fiyat veya bir ISO kodu için.

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

Kredi

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

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

Teklif

Göndermeden bir gönderiyi fiyatlandırır. Gönder ile aynı metni alır.

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

Gönder

Bir kampanya oluşturur, toplamını kredinizden alır ve mesajları sıraya koyar. Kampanya ile 201 yanıtı verir. Gönderilemeyen numaralar left_out içinde listelenir ve asla ücretlendirilmez.

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

Kampanyalar

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}

Tek bir kampanya, durum başına sayıları içerir: sıraya alındı, gönderildi, teslim edildi, başarısız oldu ve iptal edildi. Mesaj listeleri sayfası after ve has_more ile; sayfa başına en fazla 1,000.

Mesajlar

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

Planlanmış bir kampanyayı iptal et

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

Başlangıç zamanına kadar çalışır. Tüm maliyet bir defter satırında kredinize iade edilir ve kampanya durumu iptal edilir olur.

Webhooklar

Konsolda bir endpoint URL'si ayarlayın. message.delivered, message.failed ve campaign.done için JSON POST ederiz, artık Test olayı gönder'e bastığınızda test. Her olay dört başlık taşır ve 10 saniye içinde herhangi bir 2xx yanıtı alındı olarak sayılır.

Teslimat 8 kez denenir: hemen, sonra 1 dakika, 5 dakika, 15 dakika, 1 saat, 3 saat, 6 saat ve 12 saat sonra. Her deneme konsol teslimat günlüğünde HTTP durumu ve yanıtınızın başlangıcıyla gösterilir.

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

İmzayı doğrula

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

Hatalar ve Limitler

Hatalar HTTP durumu ve bir JSON gövdesi kullanır: {"error":{"code":"insufficient_credit","message":"..."}}. İstek başarısız olduğunda hiçbir ücret alınmaz.

Her cevap X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset taşır.

Dışarıda bırakılan kodlar

Fiyatlandırmadan önce kaldırılan numaralar, listedeki konumları, gönderdiğiniz değer, bir kod ve basit neden ile left_out içinde geri döner.

Durumlar ve nedenler

API hakkında sorularınız mı var? Konsolda bir bilet açın veya SSS'yi okuyun.