Mengirim
Kirim SMS massal dengan POST /v1/batches
/v1/batchesKirim ke maksimal 10.000 nomor dalam satu permintaan. Seluruh biaya langsung dipotong dari saldo.
Bodi permintaan
- toarray of stringsopsional
Nomor untuk satu teks bersama. Gunakan to dengan text, atau messages.
- textstringopsional
Teks bersama, wajib jika menggunakan to.
- messagesarray of objectsopsional
Satu {to, text} per penerima, untuk teks personal.
- namestringopsional
Label untuk konsol, maksimal 100 karakter.
- referencestringopsional
ID Anda sendiri, maksimal 100 karakter, dikembalikan pada batch dan setiap pesan.
- send_atstringopsional
Waktu ISO 8601, 2 menit sampai 45 hari ke depan.
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": []
}Nomor yang disisihkan
Setiap nomor dibersihkan dan diharga sendiri. Nomor yang tidak bisa dikirim dikeluarkan dari batch, tidak dikenakan biaya, dan dicantumkan di set_aside dengan alasan:
| reason | Arti |
|---|---|
| invalid_number | Tidak terbaca sebagai + dan 7 sampai 15 digit setelah pembersihan. |
| duplicate | Nomor yang sama muncul sebelumnya dalam permintaan. |
| unsupported_country | Nomor tidak termasuk negara yang memiliki harga. |
| too_long | Teks personalnya membutuhkan lebih dari 10 segmen. |
| empty_text | Teks personalnya kosong. |
| suppressed | Nomor ada dalam daftar do-not-send Anda. |
Jika tidak ada nomor yang tersisa, permintaan gagal dengan kode alasan pertama (contoh invalid_number) dan tidak ada yang dikenakan biaya.
Teks personal per nomor
Gunakan messages untuk memberikan teks personal ke setiap penerima: nama, waktu, jumlah. Setiap teks dihitung dan diharga sendiri, sehingga batch bisa mencampur pesan 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." }
]
}'Penjadwalan
Dengan send_at, batch dan pesannya menunggu dalam status scheduled dan pindah ke antrian pada menit tersebut. Biaya dipotong saat permintaan diterima, jadi batch terjadwal selalu memiliki dananya. Batch terjadwal bisa dibatalkan sampai mulai dikirim.
/v1/batches/{id}/cancelMembatalkan batch terjadwal: setiap pesan menjadi canceled dan seluruh biaya dikembalikan ke saldo sebagai satu baris refund. Batch yang sudah mulai mengembalikan 409 not_cancelable.
curl -X POST https://bulksmsapi.cc/v1/batches/bat_6TQ2W8M1ZK4N/cancel \
-H "Authorization: Bearer $BULKSMSAPI_KEY"Ambil dan daftar batch
/v1/batches/{id}Batch dengan jumlah live per status. Poll untuk memantau progres, atau gunakan webhooks.
/v1/batchesBatch dari akun, yang terbaru pertama, dengan limit (1 hingga 100) dan starting_after (id bat_).
Kolom batch
- idstring
bat_ diikuti oleh 12 karakter.
- statusstring
scheduled, queued, sending, completed, atau canceled.
- sourcestring
api atau console.
- encodingstring
GSM-7, atau UCS-2 jika teks memerlukan Unicode.
- recipientsinteger
Nomor yang diterima ke dalam batch.
- max_segmentsinteger
Jumlah segmen terbesar di antara teks.
- coststring
Total yang diambil dari saldo, USD.
- refundedstring
Total yang dikembalikan sejauh ini untuk pesan yang gagal atau dibatalkan.
- countsobject
Pesan per status: scheduled, queued, sent, delivered, failed, canceled.
- send_atstring or null
Waktu terjadwal, jika ada.
- completed_atstring or null
Ketika pesan terakhir mencapai status akhir.
Daftar lebih besar
Pisahkan daftar lebih dari 10.000 nomor menjadi beberapa permintaan, masing-masing dengan Idempotency-Key sendiri (misalnya id daftar dan nomor bagian). Pesan diserahkan ke jaringan secara berurutan hingga 1.200 per menit per akun, sehingga kampanye 50.000 nomor akan selesai dalam waktu kurang dari satu jam. Console menerima 50.000 nomor per kampanye dari tempel atau file CSV.