Menghantar
Hantar SMS pukal dengan POST /v1/batches
/v1/batchesHantar kepada sehingga 10,000 nombor dalam satu permintaan. Keseluruhan kos diambil dari saldo sekaligus.
Badan permintaan
- toarray of stringspilihan
Nombor untuk satu teks kongsi. Gunakan sama ada to dengan text, atau messages.
- textstringpilihan
Teks kongsi, diperlukan dengan to.
- messagesarray of objectspilihan
Satu {to, text} setiap penerima, untuk teks peribadi.
- namestringpilihan
Label untuk konsol, sehingga 100 aksara.
- referencestringpilihan
ID anda sendiri, sehingga 100 aksara, dikembalikan pada kumpulan dan setiap mesej.
- send_atstringpilihan
Masa ISO 8601, 2 minit hingga 45 hari ke hadapan.
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": []
}Nombor yang diketepikan
Setiap nombor dibersihkan dan diharga secara berasingan. Nombor yang tidak boleh dihantar dikecualikan dari kumpulan, tidak dikenakan bayaran, dan disenaraikan dalam set_aside dengan sebab:
| reason | Maksud |
|---|---|
| invalid_number | Tidak boleh dibaca sebagai + dan 7 hingga 15 digit selepas pembersihan. |
| duplicate | Nombor sama muncul lebih awal dalam permintaan. |
| unsupported_country | Nombor tersebut bukan milik negara berharga. |
| too_long | Teks peribadinya memerlukan lebih daripada 10 segmen. |
| empty_text | Teks peribadinya kosong. |
| suppressed | Nombor tersebut dalam senarai jangan-hantar anda. |
Jika tiada nombor tinggal, permintaan gagal dengan kod sebab pertama (contohnya invalid_number) dan tiada apa dikenakan bayaran.
Teks peribadi setiap nombor
Gunakan messages untuk beri setiap penerima teks mereka sendiri: nama, masa, jumlah. Setiap teks dikira dan diharga secara berasingan, jadi kumpulan boleh campur mesej satu segmen dan dua segmen.
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." }
]
}'Penjadualan
Dengan send_at, kumpulan dan mesejnya menunggu dalam status scheduled dan berpindah ke barisan pada minit tersebut. Kos diambil apabila permintaan diterima, jadi kumpulan terjadual sentiasa ada dana. Kumpulan terjadual boleh dibatalkan sehingga ia bermula.
/v1/batches/{id}/cancelMembatalkan kumpulan terjadual: setiap mesej menjadi dibatalkan dan kos penuh dikembalikan ke saldo sebagai satu barian bayaran balik. Kumpulan yang telah bermula menjawab 409 not_cancelable.
curl -X POST https://bulksmsapi.cc/v1/batches/bat_6TQ2W8M1ZK4N/cancel \
-H "Authorization: Bearer $BULKSMSAPI_KEY"Dapatkan dan senaraikan kumpulan
/v1/batches/{id}Batch dengan kiraan status terkini. Poll untuk kemajuan, atau gunakan webhooks.
/v1/batchesBatch akaun, terbaru dahulu, dengan limit (1 hingga 100) dan starting_after (id bat_).
Medan batch
- idstring
bat_ diikuti oleh 12 aksara.
- statusstring
scheduled, queued, sending, completed atau canceled.
- sourcestring
api atau console.
- encodingstring
GSM-7, atau UCS-2 jika teks memerlukan Unicode.
- recipientsinteger
Nombor yang diterima dalam batch.
- max_segmentsinteger
Kiraan segmen terbesar dalam teks.
- coststring
Jumlah diambil dari saldo, USD.
- refundedstring
Jumlah dikembalikan setakat ini untuk mesej gagal atau dibatalkan.
- countsobject
Mesej mengikut status: scheduled, queued, sent, delivered, failed, canceled.
- send_atstring or null
Masa dijadualkan, jika ada.
- completed_atstring or null
Bila mesej terakhir mencapai status akhir.
Senarai lebih besar
Pisahkan senarai melebihi 10,000 nombor kepada beberapa permintaan, masing-masing dengan Idempotency-Key sendiri (contohnya id senarai dan nombor bahagian). Mesej diserahkan kepada rangkaian mengikut urutan sehingga 1,200 seminit setiap akaun, jadi kempen 50,000 nombor akan dihantar dalam masa kurang sejam. Konsol menerima 50,000 nombor setiap kempen dari tampalan atau fail CSV.