Gửi tin
Gửi SMS hàng loạt với POST /v1/batches
/v1/batchesGửi tới tối đa 10,000 số trong một yêu cầu. Toàn bộ chi phí được trừ từ số dư ngay lập tức.
Nội dung yêu cầu
- toarray of stringstùy chọn
Số dùng chung một tin nhắn. Dùng to với text, hoặc messages.
- textstringtùy chọn
Tin nhắn dùng chung, bắt buộc khi dùng to.
- messagesarray of objectstùy chọn
Một {to, text} cho mỗi người nhận, dành cho tin nhắn cá nhân.
- namestringtùy chọn
Nhãn cho console, tối đa 100 ký tự.
- referencestringtùy chọn
ID riêng của bạn, tối đa 100 ký tự, được trả về trên lô và mỗi tin nhắn.
- send_atstringtùy chọn
Thời gian ISO 8601, từ 2 phút đến 45 ngày sau.
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": []
}Số bị loại
Mỗi số được làm sạch và định giá riêng. Số không thể gửi bị loại khỏi lô, không bị tính phí, và liệt kê trong set_aside với lý do:
| reason | Ý nghĩa |
|---|---|
| invalid_number | Không đọc được dưới dạng + và 7 đến 15 chữ số sau khi làm sạch. |
| duplicate | Số này đã xuất hiện trước đó trong yêu cầu. |
| unsupported_country | Số không thuộc quốc gia có giá. |
| too_long | Tin nhắn cá nhân cần nhiều hơn 10 segment. |
| empty_text | Tin nhắn cá nhân trống. |
| suppressed | Số có trong danh sách không gửi của bạn. |
Nếu không còn số nào, yêu cầu thất bại với mã lý do đầu tiên (ví dụ invalid_number) và không bị tính phí.
Tin nhắn cá nhân cho từng số
Dùng messages để gửi tin nhắn riêng cho từng người nhận: tên, thời gian, số tiền. Mỗi tin nhắn được đếm và định giá riêng, nên một lô có thể trộn tin nhắn một segment và hai segment.
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." }
]
}'Lập lịch
Với send_at, lô và tin nhắn sẽ chờ ở trạng thái scheduled và chuyển vào hàng đợi vào phút đó. Chi phí được trừ khi yêu cầu được chấp nhận, nên lô đã lên lịch luôn có đủ tiền. Có thể hủy lô đã lên lịch cho đến khi bắt đầu.
/v1/batches/{id}/cancelHủy một lô đã lên lịch: mọi tin nhắn chuyển thành canceled và toàn bộ chi phí được hoàn vào số dư dưới dạng một dòng hoàn tiền. Lô đã bắt đầu sẽ trả về 409 not_cancelable.
curl -X POST https://bulksmsapi.cc/v1/batches/bat_6TQ2W8M1ZK4N/cancel \
-H "Authorization: Bearer $BULKSMSAPI_KEY"Truy xuất và liệt kê các lô
/v1/batches/{id}Batch với số lượng trạng thái cập nhật theo thời gian thực. Bạn có thể kiểm tra tiến trình bằng cách poll hoặc sử dụng webhooks.
/v1/batchesCác batch của tài khoản, sắp xếp từ mới nhất trở đi, với giới hạn (từ 1 đến 100) và starting_after (một bat_ id).
Các trường của batch
- idstring
bat_ theo sau là 12 ký tự.
- statusstring
scheduled, queued, sending, completed hoặc canceled.
- sourcestring
api hoặc console.
- encodingstring
GSM-7, hoặc UCS-2 khi bất kỳ văn bản nào cần Unicode.
- recipientsinteger
Số điện thoại được chấp nhận vào batch.
- max_segmentsinteger
Số lượng segment lớn nhất trong các văn bản.
- coststring
Tổng số tiền được trừ từ số dư, USD.
- refundedstring
Tổng số tiền được hoàn trả cho đến nay cho các tin nhắn thất bại hoặc đã hủy.
- countsobject
Tin nhắn theo trạng thái: scheduled, queued, sent, delivered, failed, canceled.
- send_atstring or null
Thời gian đã lên lịch, nếu có.
- completed_atstring or null
Khi tin nhắn cuối cùng đạt trạng thái cuối cùng.
Danh sách lớn hơn
Chia danh sách trên 10,000 số thành nhiều yêu cầu, mỗi yêu cầu có Idempotency-Key riêng (ví dụ: id danh sách và số phần). Tin nhắn được chuyển đến mạng theo thứ tự với tốc độ tối đa 1,200 tin mỗi phút cho mỗi tài khoản, vì vậy một chiến dịch 50,000 số sẽ được gửi đi trong vòng chưa đầy một giờ. Console nhận 50,000 số cho mỗi chiến dịch từ một file paste hoặc CSV.