बल्क SMS API दस्तावेज़ीकरण

त्वरित प्रारंभ

1. कंसोल में एक खाता बनाएं और अपना बैलेंस टॉप अप करें।
2. API कुंजियाँ खोलें और एक कुंजी बनाएं। पहली टॉप-अप जमा होने के बाद कुंजियाँ बनाई जा सकती हैं। कुंजी केवल एक बार दिखाई जाती है; इसे एक गुप्त के रूप में संग्रहित करें।
3. नंबरों और पाठ के साथ /sms पर एक POST अनुरोध भेजें। लौटाए गए अभियान ID को पढ़ें, फिर कंसोल में या वेबहुक के माध्यम से डिलीवरी का पालन करें।

प्रमाणीकरण

सार्वजनिक दर सूची को छोड़कर प्रत्येक अनुरोध आपकी कुंजी को Authorization हेडर में ले जाता है। कुंजियाँ sbk_live_ से शुरू होती हैं। एक नई कुंजी तुरंत पुरानी को प्रतिस्थापित करती है।

Authorization: Bearer sbk_live_YOUR_KEY

एसएमएस भेजें

POST/sms

एक अभियान बनाता है, इसे बैलेंस से चार्ज करता है और प्रत्येक संदेश को कतार में डालता है। नंबरों को साफ और डी-डुप्लिकेट किया जाता है; जिनका उपयोग नहीं किया जा सकता है, उन्हें dropped में एक कारण के साथ लौटाया जाता है और उन पर शुल्क नहीं लगाया जाता है।

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"];

प्रतिक्रिया: अभियान इसकी लागत और पहले 1,000 संदेशों के साथ। अभियान संदेशों के साथ और अधिक प्राप्त करें।

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

भेजने का अनुमान लगाएं

POST/estimate

/sms के समान बॉडी लेता है और प्राप्तकर्ताओं, सेगमेंट, एन्कोडिंग, कुल लागत और प्रति देश लागत को चार्ज या भेजे बिना लौटाता है।

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

संदेश स्थिति

GET/sms/{message_id}

एक संदेश लौटाता है: नंबर, देश, सेगमेंट, मूल्य, स्थिति, विफल संदेशों के लिए त्रुटि और प्रत्येक चरण का समय।

अभियान

GET/campaigns/{campaign_id}

अभियान इसकी लागत, धनवापसी और प्रति स्थिति संदेशों की गिनती के साथ।

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

संदेश उसी क्रम में कतारबद्ध किए गए, प्रति पृष्ठ 1,000 तक।

POST/campaigns/{campaign_id}/cancel

एक निर्धारित अभियान को रद्द करता है जो शुरू नहीं हुआ है और इसकी पूरी लागत को बैलेंस में वापस कर देता है।

बैलेंस और दरें

GET/balance

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

GET/rates

सार्वजनिक, कुंजी की आवश्यकता नहीं है। प्रत्येक देश इसके कॉलिंग कोड और प्रति सेगमेंट मूल्य के साथ। /rates/GB एक देश लौटाता है।

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

डिलीवरी वेबहुक

API कुंजियों के तहत कंसोल में एक वेबहुक URL सेट करें। जब एक संदेश अंतिम स्थिति (डिलीवर या विफल) तक पहुँचता है, तो हम इस पर एक रिपोर्ट POST करते हैं। 8 सेकंड के भीतर किसी भी 2xx स्थिति के साथ उत्तर दें; अन्यथा कॉल को लगभग 11 घंटे में 8 बार तक पुनः प्रयास किया जाता है। id का उपयोग उस रिपोर्ट को अनदेखा करने के लिए करें जिसे आपने पहले ही संसाधित कर लिया है।

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

रिपोर्ट पर भरोसा करने से पहले हस्ताक्षर की जाँच करें: आपके वेबहुक सीक्रेट के साथ t + "." + raw body का HMAC-SHA256, निरंतर समय में तुलना की गई, और 5 मिनट से पुराने समय को अस्वीकार करें।

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]);
}

स्थितियाँ

त्रुटियाँ

त्रुटियां HTTP स्थिति कोड और एक JSON बॉडी का उपयोग करती हैं: { "error": { "code": "insufficient_balance", "message": "..." } }। एक अनुरोध जो त्रुटि देता है, बैलेंस को कभी चार्ज नहीं करता है।

सीमाएँ

• प्रति API कुंजी एक मिनट में 300 अनुरोध।
• प्रति भेजने के अनुरोध में 10,000 नंबर; प्रति संदेश 10 सेगमेंट।
• संदेश प्रति कतार में एक मिनट में 200 तक छोड़ते हैं, जिस क्रम में उन्हें स्वीकार किया गया था।
• 5 मिनट से 60 दिन आगे तक शेड्यूलिंग।
• आपकी डू-नॉट-सेंड सूची पर नंबर छोड़ दिए जाते हैं और कोड suppressed के साथ dropped में लौटाए जाते हैं; उन्हें चार्ज नहीं किया जाता है।