Pagsusumite
Magpadala ng bulk SMS gamit ang POST /v1/batches
/v1/batchesMagpadala sa hanggang 10,000 numero sa isang request. Ang buong halaga ay kinuha mula sa balance nang sabay-sabay.
Request body
- toarray of stringsopsyonal
Mga numero para sa isang shared text. Gamitin ang alinman sa to kasama ang text, o messages.
- textstringopsyonal
Ang shared text, kinakailangan kasama ang to.
- messagesarray of objectsopsyonal
Isang {to, text} bawat tatanggap, para sa personal na mga text.
- namestringopsyonal
Isang label para sa console, hanggang 100 karakter.
- referencestringopsyonal
Ang iyong sariling id, hanggang 100 karakter, ibinalik sa batch at bawat mensahe.
- send_atstringopsyonal
Oras sa ISO 8601, 2 minuto hanggang 45 araw sa hinaharap.
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": []
}Mga numerong itinabi
Bawat numero ay nilinis at pinresyo nang mag-isa. Ang mga numerong hindi maipapadala ay hindi kasama sa batch, hindi sisingilin, at nakalista sa set_aside na may dahilan:
| reason | Kahulugan |
|---|---|
| invalid_number | Hindi mabasa bilang + at 7 hanggang 15 digit pagkatapos linisin. |
| duplicate | Ang parehong numero ay lumabas na mas maaga sa request. |
| unsupported_country | Ang numero ay hindi kabilang sa isang priced country. |
| too_long | Ang personal na text nito ay nangangailangan ng higit sa 10 segment. |
| empty_text | Ang personal na text nito ay walang laman. |
| suppressed | Ang numero ay nasa iyong do-not-send list. |
Kung walang natirang numero, ang request ay magfa-fail sa code ng unang dahilan (halimbawa invalid_number) at walang sisingilin.
Personal na text bawat numero
Gamitin ang messages para bigyan ang bawat tatanggap ng kanilang sariling text: mga pangalan, oras, halaga. Ang bawat text ay binibilang at pinpresyo nang mag-isa, kaya ang isang batch ay maaaring maghalo ng one-segment at two-segment na mga mensahe.
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." }
]
}'Pag-iiskedyul
Sa send_at ang batch at mga mensahe nito ay naghihintay sa status na scheduled at lilipat sa queue sa minutong iyon. Ang halaga ay kinukuha kapag ang request ay tinanggap, kaya ang isang scheduled batch ay laging may pondo nito. Ang isang scheduled batch ay maaaring kanselahin hanggang sa ito ay magsimula.
/v1/batches/{id}/cancelKinakansela ang isang scheduled batch: ang bawat mensahe ay magiging canceled at ang buong halaga ay babalik sa balance bilang isang refund line. Ang isang batch na nagsimula na ay magsasagot ng 409 not_cancelable.
curl -X POST https://bulksmsapi.cc/v1/batches/bat_6TQ2W8M1ZK4N/cancel \
-H "Authorization: Bearer $BULKSMSAPI_KEY"Kunin at ilista ang mga batch
/v1/batches/{id}Ang batch na may live counts bawat status. Subaybayan ito para sa progreso, o gumamit ng webhooks.
/v1/batchesMga batch ng account, pinakabago muna, may limit (1 hanggang 100) at starting_after (isang bat_ id).
Mga field ng batch
- idstring
bat_ na sinusundan ng 12 karakter.
- statusstring
scheduled, queued, sending, completed o canceled.
- sourcestring
api o console.
- encodingstring
GSM-7, o UCS-2 kapag kailangan ng Unicode ang anumang text.
- recipientsinteger
Mga numerong tinanggap sa batch.
- max_segmentsinteger
Pinakamalaking segment count sa mga text.
- coststring
Kabuuang kinuha mula sa balance, USD.
- refundedstring
Kabuuang ibinalik para sa mga nabigo o nakanselang mensahe.
- countsobject
Mga mensahe bawat status: scheduled, queued, sent, delivered, failed, canceled.
- send_atstring or null
Scheduled time, kung meron.
- completed_atstring or null
Nang maabot ng huling mensahe ang final status.
Mas malalaking listahan
Hatiin ang mga listahan na may higit sa 10,000 numero sa ilang request, bawat isa ay may sariling Idempotency-Key (halimbawa, ang list id at part number). Ang mga mensahe ay ipapasa sa network nang sunud-sunod hanggang 1,200 kada minuto bawat account, kaya ang isang 50,000-number campaign ay magsisimula sa loob ng isang oras. Ang console ay tumatanggap ng 50,000 numero kada campaign mula sa paste o CSV file.