बल्क SMS API v1

अपने सॉफ़्टवेयर से बल्क एसएमएस भेजने के लिए एक छोटा REST API: JSON इन और आउट, Bearer कुंजियाँ, कंसोल के समान कीमतें और जाँच, और डिलीवरी रिपोर्ट के लिए साइन किए गए वेबहुक्स। बेस URL https://smsbulk.cc/rest/v1

अवलोकन

प्रति अनुरोध 8,000 नंबरों तक भेजें, प्रत्येक के अपने मर्ज मानों के साथ, और API प्रत्येक प्राप्तकर्ता को उनके अपने मर्ज किए गए टेक्स्ट के साथ कीमतें देता है, ठीक कंसोल की तरह। लागत जानने के लिए पहले उसी बॉडी के साथ कोटेशन मांगें; कोटेशन द्वारा कुछ भी भेजा या चार्ज नहीं किया जाता है। समय ISO 8601 में UTC है, पैसा पाँच दशमलव स्थानों के साथ अमेरिकी डॉलर में एक स्ट्रिंग है।

curl https://smsbulk.cc/rest/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      { "to": "+14155550142", "fields": { "name": "Maria" } },
      { "to": "+447400123456", "fields": { "name": "Tom" } }
    ],
    "text": "Hi {{name}}, your order ships today.",
    "client_ref": "order-batch-17"
  }'

const res = await fetch("https://smsbulk.cc/rest/v1/send", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    recipients: [
      { to: "+14155550142", fields: { name: "Maria" } },
      { to: "+447400123456", fields: { name: "Tom" } },
    ],
    text: "Hi {{name}}, your order ships today.",
    client_ref: "order-batch-17",
  }),
});
const data = await res.json();
console.log(res.status, data.campaign?.id, data.campaign?.cost);

import requests

res = requests.post(
    "https://smsbulk.cc/rest/v1/send",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "recipients": [
            {"to": "+14155550142", "fields": {"name": "Maria"}},
            {"to": "+447400123456", "fields": {"name": "Tom"}},
        ],
        "text": "Hi {{name}}, your order ships today.",
        "client_ref": "order-batch-17",
    },
    timeout=30,
)
data = res.json()
print(res.status_code, data.get("campaign", {}).get("id"))

<?php
$body = json_encode([
  "recipients" => [
    ["to" => "+14155550142", "fields" => ["name" => "Maria"]],
    ["to" => "+447400123456", "fields" => ["name" => "Tom"]],
  ],
  "text" => "Hi {{name}}, your order ships today.",
  "client_ref" => "order-batch-17",
]);
$ch = curl_init("https://smsbulk.cc/rest/v1/send");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_API_KEY", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => $body,
]);
$data = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), " ", $data["campaign"]["id"] ?? "", PHP_EOL;

प्रमाणीकरण

API और वेबहुक्स के तहत कंसोल में एक कुंजी बनाएं; कुंजियाँ आपके पहले क्रेडिट किए गए टॉप-अप के बाद खुलती हैं। इसे प्रत्येक अनुरोध पर Bearer टोकन के रूप में भेजें। एक कुंजी एक बार दिखाई जाती है; आप 5 कुंजियाँ तक रख सकते हैं और उनमें से किसी को भी तुरंत रद्द कर सकते हैं।

Authorization: Bearer smsb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

दरें

सार्वजनिक, कुंजी की आवश्यकता नहीं है। प्रत्येक गंतव्य के लिए प्रति एसएमएस सेगमेंट की कीमत, या एक 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

फील्ड	टाइप	मतलब
to	string or string[]	एक नंबर या लिस्ट। + के साथ इंटरनेशनल फॉर्म सबसे सुरक्षित है; लोकल नंबर के लिए default_country की जरूरत होती है।
recipients	object[]	to के बजाय: { to, fields } की एक लिस्ट जहां fields मर्ज फील्ड्स को भरते हैं जैसे {{name}}।
text	string	मर्ज करने के बाद संदेश, 2,000 कैरेक्टर और 10 सेगमेंट तक।
default_country	string	+ के बिना लिखे गए नंबर के लिए उपयोग किया जाने वाला ISO कोड, जैसे GB। सेटिंग्स में सेव्ड डिफॉल्ट पर वापस आता है।
opt_out	boolean	आपके सेव्ड ऑप्ट-आउट वर्डिंग को आखिरी लाइन के रूप में जोड़ता है (पहले इसे सेटिंग्स में सेव करें)।

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

फील्ड	टाइप	मतलब
to / recipients / text / default_country / opt_out		जैसा कि Quote में है।
send_at	string	शुरू करने के लिए ISO 8601 समय, 5 मिनट से 90 दिन आगे। अभी भेजने के लिए छोड़ दें।
name	string	कैंपेन के लिए आपका लेबल, 80 कैरेक्टर तक।
client_ref	string	आपका अपना रेफरेंस, 64 कैरेक्टर तक, हर मैसेज और वेबहुक पर वापस आता है।

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 सेट करें। हम message.delivered, message.failed और campaign.done के लिए JSON POST करते हैं, साथ ही जब आप Send test event दबाते हैं तो टेस्ट करते हैं। प्रत्येक इवेंट चार हेडर ले जाता है, और 10 सेकंड के भीतर कोई भी 2xx उत्तर प्राप्त के रूप में गिना जाता है।

फील्ड	टाइप	मतलब
Smsbulk-Event	हेडर	इवेंट नाम, जैसे message.delivered।
Smsbulk-Delivery	हेडर	डिलीवरी आईडी, एक इवेंट के हर रिट्राई पर समान।
Smsbulk-Timestamp	हेडर	यूनिक्स सेकंड जब यह प्रयास साइन किया गया था।
Smsbulk-Signature	हेडर	sha256= जिसके बाद टाइमस्टैम्प, एक न्यूलाइन और रॉ बॉडी का base64 HMAC-SHA256 होता है, जो आपके sbw_ सीक्रेट से कीड होता है।

डिलीवरी 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":"..."}}. रिक्वेस्ट फेल होने पर कोई चार्ज नहीं लगता।

फील्ड	टाइप	मतलब
400 bad_json		बॉडी JSON नहीं है।
401 unauthorized		गायब, गलत फॉर्मेट या रिवोक्ड की।
402 insufficient_credit		कुल राशि आपके क्रेडिट से अधिक है। कंसोल में फंड जोड़ें।
404 not_found		इस खाते पर ऐसा कोई एंडपॉइंट, कैंपेन, संदेश या ISO कोड नहीं है।
409 not_scheduled		एक ऐसे कैंपेन के लिए कैंसल का अनुरोध किया गया जो पहले ही शुरू हो चुका है।
422 text_missing, text_too_long, too_many_segments		संदेश खाली है, 2,000 वर्णों से अधिक है, या एक प्राप्तकर्ता के लिए 10 सेगमेंट से अधिक है।
422 no_recipients, too_many, recipients_missing		कोई भेजने योग्य नंबर नहीं है, 8,000 नंबरों से अधिक है, या ना तो 'to' और ना ही 'recipients' है।
422 schedule_range, bad_send_at		send_at 5 मिनट से 90 दिनों के बाहर है, या एक वैध समय नहीं है।
422 opt_out_unset		opt_out सही है लेकिन सेटिंग्स में कोई वाक्यांश सहेजा नहीं गया है।
429 rate_limited		इस कुंजी के लिए एक मिनट में 300 से अधिक अनुरोध हैं।

हर जवाब में X-RateLimit-Limit, X-RateLimit-Remaining और X-RateLimit-Reset होता है।

छोड़े गए कोड

प्राइसिंग से पहले हटाए गए नंबर left_out में वापस आते हैं, जिसमें आपकी लिस्ट में उनकी पोजीशन, आपके द्वारा भेजा गया वैल्यू, एक कोड और स्पष्ट कारण शामिल होता है।

फील्ड	टाइप	मतलब
no_country_code		कोई + और कोई डिफ़ॉल्ट देश नहीं है।
too_short / too_long		8 से कम या 15 से अधिक अंक।
not_a_number		अक्षर या प्रतीक जो किसी नंबर का हिस्सा नहीं हैं।
nanp_length		एक +1 नंबर जिसमें ग्यारह अंक नहीं हैं।
not_covered		हमारी सूची के बाहर एक गंतव्य।
duplicate		यही नंबर अनुरोध में पहले आ चुका है।
suppressed		यह नंबर आपकी 'डू-नॉट-सेंड' सूची पर है।

स्टेटस और कारण

फील्ड	टाइप	मतलब
queued	स्थिति	हमारी कतार से निकलने की प्रतीक्षा में।
sent	स्थिति	नेटवर्क को सौंप दिया गया है, डिलीवरी रिपोर्ट की प्रतीक्षा में। अधिकांश रिपोर्ट कुछ मिनटों में आ जाती हैं; कुछ नेटवर्क 24 घंटे तक ले सकते हैं।
delivered	स्थिति	नेटवर्क ने पुष्टि की कि फोन ने इसे प्राप्त कर लिया है।
failed	स्थिति	डिलीवर नहीं हुआ। कीमत आपके क्रेडिट में वापस कर दी गई है।
canceled	स्थिति	नहीं भेजा गया क्योंकि आपने कैंसल कर दिया। वापस कर दिया गया।

फील्ड	टाइप	मतलब
network_error	कारण	नेटवर्क त्रुटि
switched_off	कारण	फोन बंद है या कवरेज से बाहर है
not_in_service	कारण	नंबर सेवा में नहीं है
blocked	कारण	नेटवर्क या प्राप्तकर्ता द्वारा ब्लॉक किया गया
landline	कारण	लैंडलाइन या नंबर जो SMS प्राप्त नहीं कर सकता
content_filter	कारण	नेटवर्क के कंटेंट फ़िल्टर द्वारा अस्वीकृत
expired	कारण	समय सीमा समाप्त: नेटवर्क की समय सीमा से पहले कोई रिपोर्ट नहीं
unknown	कारण	अज्ञात नेटवर्क प्रतिक्रिया
canceled	कारण	भेजने से पहले रद्द किया गया

API के बारे में सवाल? कंसोल में एक टिकट खोलें, या FAQ पढ़ें।