Bắt đầu
Tài liệu API Bulk SMS
BulkSMSAPI là API SMS hàng loạt cho nhà phát triển: gửi một tin nhắn hoặc một batch tới 10,000 số mỗi yêu cầu tới 227 quốc gia qua REST, theo dõi mọi tin nhắn bằng webhooks có chữ ký, và thanh toán theo tin từ số dư trả trước. Tài liệu này bao phủ mọi endpoint, trường, sự kiện và lỗi của API. Mỗi trang cũng có sẵn dạng Markdown: thêm .md vào địa chỉ.
URL cơ sở và định dạng
Mọi yêu cầu gửi tới https://bulksmsapi.cc/v1 qua HTTPS. Nội dung là JSON (Content-Type: application/json, UTF-8), và mọi phản hồi đều là JSON, bao gồm lỗi. Thời gian theo ISO 8601 UTC. Tiền tệ là chuỗi USD với năm số thập phân ("0.00507"), nên giá dưới 1 cent vẫn chính xác.
Các endpoint
| Phương thức và đường dẫn | Chức năng | Key |
|---|---|---|
| POST /v1/messages | Gửi một tin tới một số | Yes |
| POST /v1/batches | Gửi tới 10,000 số, một tin chung hoặc riêng từng số | Yes |
| GET /v1/messages/{id} | Một tin nhắn với trạng thái và giá | Yes |
| GET /v1/messages | Tin nhắn, mới nhất trước, lọc theo batch hoặc trạng thái | Yes |
| GET /v1/batches/{id} | Một batch với số lượng theo từng trạng thái | Yes |
| GET /v1/batches | Các batch, mới nhất trước | Yes |
| POST /v1/batches/{id}/cancel | Hủy batch đã lên lịch, hoàn tiền đầy đủ | Yes |
| POST /v1/estimates | Tính giá một yêu cầu mà không gửi | Yes |
| GET /v1/balance | Số dư bằng USD | Yes |
| GET /v1/pricing | Giá mỗi segment cho mọi quốc gia | No |
| GET /v1/pricing/{country} | Giá cho một quốc gia (mã ISO) | No |
Yêu cầu đầu tiên
Tạo API key trong console, xuất nó ra và gửi tin nhắn. Phản hồi sẽ là 202 với đối tượng tin nhắn: chi phí được trừ từ số dư và tin nhắn được đưa vào hàng đợi.
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
}Hành trình tin nhắn
Tin nhắn được chấp nhận sẽ ở trạng thái queued (hoặc scheduled nếu yêu cầu có send_at). Hàng đợi chuyển chúng tới mạng mỗi 2 giây, tối đa 1,200 tin mỗi phút mỗi tài khoản, và chúng chuyển sang trạng thái sent. Trạng thái cuối cùng là delivered hoặc failed; tin nhắn thất bại sẽ được hoàn tiền ngay lập tức vào số dư. Mỗi trạng thái cuối sẽ gọi webhook của bạn với một sự kiện đã ký.
Tổng quan giới hạn
| Giới hạn | Giá trị |
|---|---|
| Người nhận mỗi yêu cầu API | 10,000 |
| Người nhận mỗi chiến dịch console | 50,000 |
| Yêu cầu mỗi phút mỗi key | 600 |
| Tin nhắn chuyển tới mạng mỗi phút mỗi tài khoản | 1,200 |
| Văn bản dài nhất | 10 segments (1,530 ký tự GSM-7 hoặc 670 ký tự UCS-2) |
| Khung thời gian lên lịch | Từ 2 phút đến 45 ngày sau |
| Số lần thử webhook mỗi sự kiện | 10 |
| Bộ nhớ Idempotency-Key | 24 giờ |
| API keys mỗi tài khoản | 10 |
Tệp máy đọc
- OpenAPI 3.1 spec dành cho trình tạo mã và client API.
- llms-full.txt: toàn bộ tài liệu tham khảo này dưới dạng file văn bản thuần túy.
- Mỗi trang tài liệu dưới dạng Markdown, ví dụ /en/docs/webhooks.md.