開始使用

Bulk SMS API 參考

BulkSMSAPI 是為開發者而設的群發 SMS API:透過 REST 每次請求可發送一則文字或最多 10,000 個號碼至 227 個國家,透過簽署的 webhooks 追蹤每則訊息,並從預付餘額按訊息付費。此參考涵蓋 API 的所有端點、欄位、事件及錯誤。每頁亦提供 Markdown 格式:在網址後加上 .md。

基礎 URL 及格式

所有請求均透過 HTTPS 發送至 https://bulksmsapi.cc/v1。請求主體為 JSON (Content-Type: application/json, UTF-8),所有回應包括錯誤均為 JSON。時間採用 ISO 8601 格式並以 UTC 表示。金額以五位小數的美元字串表示 ("0.00507"),因此低於一美分的價格亦能精確顯示。

端點

方法及路徑功能Key
POST /v1/messages發送一則文字至一個號碼Yes
POST /v1/batches發送至最多 10,000 個號碼,一則文字或每號碼一則Yes
GET /v1/messages/{id}一則訊息及其狀態與價格Yes
GET /v1/messages訊息,最新優先,按批次或狀態篩選Yes
GET /v1/batches/{id}單一批次及各狀態數量Yes
GET /v1/batches批次,最新優先Yes
POST /v1/batches/{id}/cancel取消已預約批次,全額退款Yes
POST /v1/estimates估算請求價格(不發送)Yes
GET /v1/balance餘額(美元)Yes
GET /v1/pricing各國每分段價格No
GET /v1/pricing/{country}單一國家價格(ISO代碼)No

首次請求

在控制台創建API密鑰,導出後發送訊息。系統將返回202狀態碼及訊息對象:費用從餘額扣除,訊息進入隊列。

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"
  }'
202 AcceptedJSON
{
  "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
}

訊息傳送流程

已接受的訊息狀態為queued(若含send_at則為scheduled)。隊列每2秒將訊息遞交網絡,每賬戶每分鐘上限1,200條,狀態轉為sent。最終狀態為delivered或failed;失敗訊息將即時退款至餘額。每項最終狀態會觸發附簽名事件的webhook。

限制一覽

限制數值
每API請求收件人數10,000
每控制台活動收件人數50,000
每密鑰每分鐘請求數600
每賬戶每分鐘遞交網絡訊息數1,200
最長文字10分段(1,530 GSM-7或670 UCS-2字符)
排程時間範圍提前2分鐘至45天
每事件webhook嘗試次數10
Idempotency-Key 記憶24小時
每賬戶API密鑰數10

機器可讀檔案

Bulk SMS API 參考 | BulkSMSAPI 文檔