Toplu SMS API dokümantasyonu

Hızlı başlangıç

1. Konsolda bir hesap oluşturun ve bakiyenizi yükleyin.
2. API anahtarları bölümünü açın ve bir anahtar oluşturun. Anahtarlar, ilk bakiye yüklemesi yapıldıktan sonra oluşturulabilir. Anahtar yalnızca bir kez gösterilir; gizli olarak saklayın.
3. Numaraları ve metni içeren bir POST isteğini /sms adresine gönderin. Dönen kampanya ID'sini okuyun, ardından teslimatı konsoldan veya webhook'lar üzerinden takip edin.

Kimlik doğrulama

Genel fiyat listesi dışındaki her istekte, Authorization başlığında anahtarınızı taşıyın. Anahtarlar sbk_live_ ile başlar. Yeni bir anahtar, eskisini hemen değiştirir.

Authorization: Bearer sbk_live_YOUR_KEY

SMS Gönder

POST/sms

Bir kampanya oluşturur, bakiyeden ücreti keser ve her mesajı sıraya alır. Numaralar temizlenir ve çiftlerden arındırılır; kullanılamayan numaralar dropped içinde bir nedenle döndürülür ve ücretlendirilmez.

curl -X POST https://sendbulksms.cc/api/v1/sms \
  -H "Authorization: Bearer sbk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["+447700900461", "+5511955550123"],
    "text": "Hi, your order 4821 ships today.",
    "client_ref": "orders-4821"
  }'

const res = await fetch("https://sendbulksms.cc/api/v1/sms", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.SENDBULKSMS_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ to: ["+447700900461", "+5511955550123"], text: "Hi, your order 4821 ships today.", client_ref: "orders-4821" }),
});
const campaign = await res.json();
console.log(res.status, campaign.id, campaign.cost);

import os, requests

r = requests.post(
    "https://sendbulksms.cc/api/v1/sms",
    headers={"Authorization": "Bearer " + os.environ["SENDBULKSMS_KEY"]},
    json={"to": ["+447700900461", "+5511955550123"], "text": "Hi, your order 4821 ships today.", "client_ref": "orders-4821"},
    timeout=30,
)
print(r.status_code, r.json()["id"])

<?php
$ch = curl_init("https://sendbulksms.cc/api/v1/sms");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("SENDBULKSMS_KEY"), "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(["to" => ["+447700900461", "+5511955550123"], "text" => "Hi, your order 4821 ships today.", "client_ref" => "orders-4821"]),
]);
$campaign = json_decode(curl_exec($ch), true);
echo $campaign["id"];

Yanıt: maliyeti ve ilk 1.000 mesajı ile kampanya. Daha fazlasını kampanya mesajları ile alın.

HTTP/1.1 201 Created
{
  "id": "CP-7KQ2-M9XA-4HTD",
  "status": "sending",
  "source": "api",
  "recipients": 2,
  "segments": 1,
  "encoding": "GSM-7",
  "cost": "0.01078",
  "refunded": "0.00000",
  "client_ref": "orders-4821",
  "scheduled_at": null,
  "created_at": "2026-11-07T10:32:04.118Z",
  "done_at": null,
  "counts": { "queued": 2, "sent": 0, "delivered": 0, "failed": 0, "canceled": 0 },
  "dropped": [],
  "balance": "248.30422",
  "messages": [
    { "id": "SM-2RBW-8MZN-QF6K", "campaign_id": "CP-7KQ2-M9XA-4HTD", "to": "+447700900461", "country": "GB", "parts": 1, "price": "0.00819", "status": "queued", "error": null, "created_at": "2026-11-07T10:32:04.118Z", "sent_at": null, "done_at": null }
  ]
}

Gönderim Tahmini Yap

POST/estimate

/sms ile aynı gövdeyi alır ve alıcıları, segmentleri, kodlamayı, toplam maliyeti ve her ülke için maliyeti ücretlendirmeden veya hiçbir şey göndermeden döndürür.

{ "recipients": 2, "dropped": [], "segments": 1, "encoding": "GSM-7", "cost": "0.01078", "balance": "248.31500",
  "countries": [ { "country": "GB", "recipients": 1, "cost": "0.00819" }, { "country": "BR", "recipients": 1, "cost": "0.00259" } ] }

Mesaj Durumu

GET/sms/{message_id}

Bir mesaj döndürür: numara, ülke, segmentler, fiyat, durum, başarısız mesajlar için hata ve her adımın zamanı.

Kampanyalar

GET/campaigns/{campaign_id}

Maliyeti, iadeleri ve durum başına mesaj sayısı ile kampanya.

GET/campaigns/{campaign_id}/messages?offset=0&limit=100

Sıraya alındıkları sırada mesajlar, sayfa başına en fazla 1.000 adet.

POST/campaigns/{campaign_id}/cancel

Başlamamış bir zamanlanmış kampanyayı iptal eder ve tam maliyetini bakiyeye iade eder.

Bakiye ve Fiyatlar

GET/balance

{ "balance": "248.31500", "currency": "USD" }

GET/rates

Genel, anahtar gerekmez. Her ülke ile arama kodu ve segment başına fiyat. /rates/GB bir ülke döndürür.

{ "updated": "2026-11-07", "rates": [ { "country": "GB", "name": "United Kingdom", "calling_code": "+44", "price": "0.00819", "currency": "USD", "unit": "SMS segment" } ] }

Teslimat Webhook'ları

API anahtarları altında konsolda bir webhook URL'si ayarlayın. Bir mesaj nihai bir duruma (teslim edildi veya başarısız) ulaştığında, bir raporu buna POST ederiz. Yaklaşık 11 saat içinde 8 kez yeniden denenir; aksi takdirde çağrı iptal edilir. Zaten işlediğiniz bir raporu görmezden gelmek için id kullanın.

POST https://your-server.example/sms-status
Content-Type: application/json
X-SendBulkSMS-Signature: t=1794047524,v1=5f0c3b9e...

{
  "event": "message.status",
  "id": "evt_8c1d2e4f6a7b9c0d1e2f",
  "created_at": "2026-11-07T10:32:09.004Z",
  "data": {
    "message_id": "SM-2RBW-8MZN-QF6K",
    "campaign_id": "CP-7KQ2-M9XA-4HTD",
    "to": "+447700900461",
    "country": "GB",
    "status": "delivered",
    "error": null,
    "parts": 1,
    "price": "0.00819",
    "client_ref": "orders-4821",
    "done_at": "2026-11-07T10:32:08.912Z"
  }
}

Bir rapora güvenmeden önce imzayı kontrol edin: webhook sırrınızla t + "." + raw body'nin HMAC-SHA256 karması, sabit zamanda karşılaştırılır ve 5 dakikadan eski zamanlar reddedilir.

import { createHmac, timingSafeEqual } from "node:crypto";

// raw = the request body exactly as received (string), header = X-SendBulkSMS-Signature
export function verify(raw, header, secret) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header || "");
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
  const want = Buffer.from(createHmac("sha256", secret).update(m[1] + "." + raw).digest("hex"));
  const got = Buffer.from(m[2]);
  return want.length === got.length && timingSafeEqual(want, got);
}

import hmac, hashlib, re, time

def verify(raw: bytes, header: str, secret: str) -> bool:
    m = re.fullmatch(r"t=(\d+),v1=([0-9a-f]{64})", header or "")
    if not m or abs(time.time() - int(m.group(1))) > 300:
        return False
    want = hmac.new(secret.encode(), m.group(1).encode() + b"." + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, m.group(2))

<?php
function verify(string $raw, string $header, string $secret): bool {
  if (!preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', $header, $m) || abs(time() - (int)$m[1]) > 300) return false;
  $want = hash_hmac('sha256', $m[1] . '.' . $raw, $secret);
  return hash_equals($want, $m[2]);
}

Durumlar

Hatalar

Hatalar HTTP durum kodları ve bir JSON gövdesi kullanır: { "error": { "code": "insufficient_balance", "message": "..." } }. Hata dönen bir istek bakiyeden ücret kesmez.

Limitler

• API anahtarı başına dakikada 300 istek.
• Gönderim isteği başına 10,000 numara; mesaj başına 10 segment.
• Mesajlar kabul edildikleri sırayla, kuyruk başına dakikada 200 adede kadar gönderilir.
• 5 dakika ile 60 gün arasında planlama yapılabilir.
• Gönderilmeyenler listesindeki numaralar atlanır ve dropped alanında suppressed koduyla döndürülür; bunlar için ücret kesilmez.