भेजना
POST /v1/batches के साथ बल्क एसएमएस भेजें
/v1/batchesएक अनुरोध में 10,000 नंबरों तक भेजें। पूरी लागत एक बार में बैलेंस से ली जाती है।
अनुरोध बॉडी
- toarray of stringsवैकल्पिक
एक साझा टेक्स्ट के लिए नंबर। टेक्स्ट के साथ या संदेशों के साथ उपयोग करें।
- textstringवैकल्पिक
साझा टेक्स्ट, to के साथ आवश्यक।
- messagesarray of objectsवैकल्पिक
प्रति प्राप्तकर्ता एक {to, text}, व्यक्तिगत टेक्स्ट के लिए।
- namestringवैकल्पिक
कंसोल के लिए एक लेबल, 100 वर्ण तक।
- referencestringवैकल्पिक
आपका अपना id, 100 वर्ण तक, बैच और हर संदेश पर वापस आता है।
- send_atstringवैकल्पिक
ISO 8601 समय, 2 मिनट से 45 दिन आगे।
curl https://bulksmsapi.cc/v1/batches \
-H "Authorization: Bearer $BULKSMSAPI_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: spring-sale-0412" \
-d '{
"name": "Spring sale",
"text": "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
"to": [
"+14155550123",
"+447400123456",
"+4915123456789"
]
}'const res = await fetch("https://bulksmsapi.cc/v1/batches", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.BULKSMSAPI_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "spring-sale-0412",
},
body: JSON.stringify({
name: "Spring sale",
text: "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
to: ["+14155550123", "+447400123456", "+4915123456789"],
}),
});
const batch = await res.json();
console.log(res.status, batch.id, batch.recipients, batch.cost);import json, os, urllib.request
req = urllib.request.Request(
"https://bulksmsapi.cc/v1/batches",
data=json.dumps({
"name": "Spring sale",
"text": "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
"to": ["+14155550123", "+447400123456", "+4915123456789"],
}).encode(),
headers={
"Authorization": "Bearer " + os.environ["BULKSMSAPI_KEY"],
"Content-Type": "application/json",
"Idempotency-Key": "spring-sale-0412",
"User-Agent": "northwind-app/1.0",
},
method="POST",
)
with urllib.request.urlopen(req) as res:
batch = json.load(res)
print(res.status, batch["id"], batch["recipients"], batch["cost"])<?php
$ch = curl_init("https://bulksmsapi.cc/v1/batches");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("BULKSMSAPI_KEY"),
"Content-Type: application/json",
"Idempotency-Key: spring-sale-0412",
],
CURLOPT_POSTFIELDS => json_encode([
"name" => "Spring sale",
"text" => "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
"to" => ["+14155550123", "+447400123456", "+4915123456789"],
]),
]);
$batch = json_decode(curl_exec($ch), true);
echo $batch["id"], " ", $batch["recipients"], " ", $batch["cost"], "\n";package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"os"
)
func main() {
body, _ := json.Marshal(map[string]any{
"name": "Spring sale",
"text": "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
"to": []string{"+14155550123", "+447400123456", "+4915123456789"},
})
req, _ := http.NewRequest("POST", "https://bulksmsapi.cc/v1/batches", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("BULKSMSAPI_KEY"))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Idempotency-Key", "spring-sale-0412")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
var batch map[string]any
json.NewDecoder(res.Body).Decode(&batch)
fmt.Println(res.StatusCode, batch["id"], batch["recipients"], batch["cost"])
}{
"id": "bat_6TQ2W8M1ZK4N",
"object": "batch",
"name": "Spring sale",
"status": "queued",
"source": "api",
"encoding": "GSM-7",
"recipients": 3,
"max_segments": 1,
"cost": "0.02741",
"refunded": "0.00000",
"currency": "USD",
"counts": { "scheduled": 0, "queued": 3, "sent": 0, "delivered": 0, "failed": 0, "canceled": 0 },
"send_at": null,
"reference": null,
"created_at": "2026-11-07T09:31:40.102Z",
"completed_at": null,
"set_aside": []
}नंबर जो सेट-असाइड हैं
हर नंबर को स्वयं साफ और मूल्यांकित किया जाता है। जिन नंबरों को भेजा नहीं जा सकता है, उन्हें बैच से बाहर छोड़ दिया जाता है, चार्ज नहीं किया जाता है, और set_aside में एक कारण के साथ सूचीबद्ध किया जाता है:
| reason | अर्थ |
|---|---|
| invalid_number | सफाई के बाद + और 7 से 15 अंकों के रूप में पठनीय नहीं। |
| duplicate | यही नंबर अनुरोध में पहले आया था। |
| unsupported_country | नंबर किसी मूल्यांकित देश से संबंधित नहीं है। |
| too_long | इसके व्यक्तिगत टेक्स्ट को 10 से अधिक सेगमेंट की आवश्यकता है। |
| empty_text | इसका व्यक्तिगत टेक्स्ट खाली है। |
| suppressed | नंबर आपकी डू-नॉट-सेंड सूची पर है। |
यदि कोई नंबर नहीं बचा है, तो अनुरोध पहले कारण के कोड (उदाहरण के लिए invalid_number) के साथ विफल हो जाता है और कुछ भी चार्ज नहीं किया जाता है।
प्रति नंबर व्यक्तिगत टेक्स्ट
प्रत्येक प्राप्तकर्ता को उनका अपना टेक्स्ट देने के लिए messages का उपयोग करें: नाम, समय, राशि। प्रत्येक टेक्स्ट को स्वयं गिना और मूल्यांकित किया जाता है, इसलिए एक बैच एक-सेगमेंट और दो-सेगमेंट संदेशों को मिला सकता है।
curl https://bulksmsapi.cc/v1/batches \
-H "Authorization: Bearer $BULKSMSAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Appointment reminders, 14 May",
"send_at": "2026-05-13T16:00:00Z",
"messages": [
{ "to": "+14155550123", "text": "Hi Ana, your dental check-up is tomorrow at 09:30." },
{ "to": "+14155550178", "text": "Hi Sam, your dental check-up is tomorrow at 11:00." }
]
}'शेड्यूलिंग
send_at के साथ बैच और उसके संदेश scheduled स्थिति में प्रतीक्षा करते हैं और उस मिनट पर कतार में चले जाते हैं। लागत तब ली जाती है जब अनुरोध स्वीकार किया जाता है, इसलिए एक शेड्यूल्ड बैच में हमेशा उसके फंड होते हैं। एक शेड्यूल्ड बैच को शुरू होने तक रद्द किया जा सकता है।
/v1/batches/{id}/cancelएक शेड्यूल्ड बैच रद्द करता है: हर संदेश रद्द हो जाता है और पूरी लागत एक रिफंड लाइन के रूप में बैलेंस में वापस आ जाती है। एक बैच जो शुरू हो चुका है, 409 not_cancelable का जवाब देता है।
curl -X POST https://bulksmsapi.cc/v1/batches/bat_6TQ2W8M1ZK4N/cancel \
-H "Authorization: Bearer $BULKSMSAPI_KEY"बैच पुनर्प्राप्त करें और सूचीबद्ध करें
/v1/batches/{id}स्टेटस के अनुसार लाइव काउंट वाला बैच। प्रगति जांचने के लिए इसे पोल करें, या वेबहुक्स का उपयोग करें।
/v1/batchesखाते के बैच, नवीनतम पहले, लिमिट (1 से 100) और starting_after (एक bat_ आईडी) के साथ।
बैच फील्ड्स
- idstring
bat_ के बाद 12 अक्षर।
- statusstring
शेड्यूल्ड, क्यूड, सेन्डिंग, कम्प्लीटेड या कैंसल्ड।
- sourcestring
एपीआई या कंसोल।
- encodingstring
GSM-7, या UCS-2 जब कोई टेक्स्ट यूनिकोड की आवश्यकता हो।
- recipientsinteger
बैच में स्वीकृत नंबर्स।
- max_segmentsinteger
टेक्स्ट्स में सबसे बड़ा सेगमेंट काउंट।
- coststring
बैलेंस से ली गई कुल राशि, USD।
- refundedstring
अब तक फेल्ड या कैंसल्ड मैसेजेस के लिए वापस की गई कुल राशि।
- countsobject
स्टेटस के अनुसार मैसेजेस: शेड्यूल्ड, क्यूड, सेन्ट, डिलीवर्ड, फेल्ड, कैंसल्ड।
- send_atstring or null
शेड्यूल्ड समय, यदि कोई हो।
- completed_atstring or null
जब अंतिम मैसेज फाइनल स्टेटस पर पहुंचा।
बड़ी सूचियाँ
10,000 से अधिक नंबर्स वाली लिस्ट्स को कई रिक्वेस्ट्स में बांटें, प्रत्येक के साथ अपनी Idempotency-Key (जैसे लिस्ट आईडी और पार्ट नंबर)। मैसेजेस को नेटवर्क को ऑर्डर में 1,200 प्रति मिनट प्रति अकाउंट की दर से भेजा जाता है, इसलिए 50,000 नंबर्स वाला कैंपेन एक घंटे से कम समय में भेजा जाता है। कंसोल पेस्ट या CSV फाइल से प्रति कैंपेन 50,000 नंबर्स लेता है।