Mulakan
Rujukan API Bulk SMS
BulkSMSAPI adalah API SMS pukal untuk pembangun: hantar satu teks atau batch sehingga 10,000 nombor setiap permintaan ke 227 negara melalui REST, ikuti setiap mesej dengan webhook yang ditandatangani, dan bayar setiap mesej dari baki prabayar. Rujukan ini merangkumi setiap endpoint, medan, acara dan ralat yang dimiliki oleh API. Setiap halaman juga tersedia sebagai Markdown: tambahkan .md pada alamatnya.
URL asas dan format
Semua permintaan dihantar ke https://bulksmsapi.cc/v1 melalui HTTPS. Badan adalah JSON (Content-Type: application/json, UTF-8), dan setiap jawapan adalah JSON, termasuk ralat. Masa adalah ISO 8601 dalam UTC. Wang adalah rentetan dalam dolar AS dengan lima perpuluhan ("0.00507"), jadi harga di bawah satu sen adalah tepat.
Endpoint
| Kaedah dan laluan | Apa yang dilakukannya | Key |
|---|---|---|
| POST /v1/messages | Hantar satu teks ke satu nombor | Yes |
| POST /v1/batches | Hantar sehingga 10,000 nombor, satu teks atau satu setiap nombor | Yes |
| GET /v1/messages/{id} | Satu mesej dengan status dan harganya | Yes |
| GET /v1/messages | Mesej, terkini dahulu, tapis mengikut batch atau status | Yes |
| GET /v1/batches/{id} | Satu batch dengan kiraan setiap status | Yes |
| GET /v1/batches | Batch, terkini dahulu | Yes |
| POST /v1/batches/{id}/cancel | Batal batch yang dijadualkan, bayaran balik penuh | Yes |
| POST /v1/estimates | Harga permintaan tanpa menghantarnya | Yes |
| GET /v1/balance | Baki dalam USD | Yes |
| GET /v1/pricing | Harga setiap segmen untuk setiap negara | No |
| GET /v1/pricing/{country} | Harga untuk satu negara (kod ISO) | No |
Permintaan pertama
Buat kunci API dalam konsol, eksportnya, dan hantar mesej. Jawapannya ialah 202 dengan objek mesej: kos diambil dari baki dan mesej disenaraikan dalam barisan.
curl https://bulksmsapi.cc/v1/messages \
-H "Authorization: Bearer $BULKSMSAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+14155550123",
"text": "Your Northwind code is 482913. It expires in 10 minutes.",
"reference": "login-7781"
}'// Node.js 18 or newer (built-in fetch)
const res = await fetch("https://bulksmsapi.cc/v1/messages", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.BULKSMSAPI_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
to: "+14155550123",
text: "Your Northwind code is 482913. It expires in 10 minutes.",
reference: "login-7781",
}),
});
const message = await res.json();
console.log(res.status, message.id, message.status, message.price);# Python 3, standard library only
import json, os, urllib.request
req = urllib.request.Request(
"https://bulksmsapi.cc/v1/messages",
data=json.dumps({
"to": "+14155550123",
"text": "Your Northwind code is 482913. It expires in 10 minutes.",
"reference": "login-7781",
}).encode(),
headers={
"Authorization": "Bearer " + os.environ["BULKSMSAPI_KEY"],
"Content-Type": "application/json",
"User-Agent": "northwind-app/1.0",
},
method="POST",
)
with urllib.request.urlopen(req) as res:
message = json.load(res)
print(res.status, message["id"], message["status"], message["price"])<?php
// PHP 7.4 or newer with the curl extension
$ch = curl_init("https://bulksmsapi.cc/v1/messages");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("BULKSMSAPI_KEY"),
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode([
"to" => "+14155550123",
"text" => "Your Northwind code is 482913. It expires in 10 minutes.",
"reference" => "login-7781",
]),
]);
$message = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), " ", $message["id"], " ", $message["status"], "\n";// Go 1.20 or newer, standard library only
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"os"
)
func main() {
body, _ := json.Marshal(map[string]any{
"to": "+14155550123",
"text": "Your Northwind code is 482913. It expires in 10 minutes.",
"reference": "login-7781",
})
req, _ := http.NewRequest("POST", "https://bulksmsapi.cc/v1/messages", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("BULKSMSAPI_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
var message map[string]any
json.NewDecoder(res.Body).Decode(&message)
fmt.Println(res.StatusCode, message["id"], message["status"], message["price"])
}{
"id": "msg_8F3K2Q9TZ1MX",
"object": "message",
"batch_id": "bat_4M7Q1X0PK2RS",
"to": "+14155550123",
"country": "US",
"text": "Your Northwind code is 482913. It expires in 10 minutes.",
"segments": 1,
"price": "0.00507",
"currency": "USD",
"status": "queued",
"error": null,
"reference": "login-7781",
"created_at": "2026-11-07T09:30:12.418Z",
"sent_at": null,
"done_at": null
}Bagaimana mesej bergerak
Mesej yang diterima adalah queued (atau scheduled apabila permintaan mempunyai send_at). Barisan menyerahkannya kepada rangkaian setiap dua saat, sehingga 1,200 seminit setiap akaun, dan ia menjadi sent. Status akhir adalah delivered atau failed; mesej yang gagal dibayar balik ke baki dengan segera. Setiap status akhir memanggil webhook anda dengan acara yang ditandatangani.
Had sekilas
| Had | Nilai |
|---|---|
| Penerima setiap permintaan API | 10,000 |
| Penerima setiap kempen konsol | 50,000 |
| Permintaan seminit setiap kunci | 600 |
| Mesej diserahkan kepada rangkaian seminit setiap akaun | 1,200 |
| Teks terpanjang | 10 segmen (1,530 GSM-7 atau 670 UCS-2 aksara) |
| Tetingkap jadual | 2 minit hingga 45 hari ke hadapan |
| Percubaan webhook setiap acara | 10 |
| Memori Idempotency-Key | 24 jam |
| Kunci API setiap akaun | 10 |
Fail yang boleh dibaca mesin
- Spesifikasi OpenAPI 3.1 untuk penjana kod dan klien API.
- llms-full.txt: keseluruhan rujukan ini sebagai satu fail teks biasa.
- Setiap halaman dokumen sebagai Markdown, contohnya /en/docs/webhooks.md.