開始使用

群發簡訊 API 參考

BulkSMSAPI 是專為開發者設計的群發簡訊 API:透過 REST 向 227 個國家發送單則簡訊或每批次最多 10,000 個號碼的請求,透過簽署的 webhooks 追蹤每則訊息,並從預付餘額中按訊息計費。本參考文件涵蓋 API 的所有端點、欄位、事件與錯誤。每個頁面也可用 Markdown 格式檢視:在網址後加上 .md。

基礎 URL 與格式

所有請求皆透過 HTTPS 發送至 https://bulksmsapi.cc/v1。請求主體為 JSON (Content-Type: application/json, UTF-8),所有回應(含錯誤)皆為 JSON 格式。時間採用 UTC 時區的 ISO 8601 格式。金額以五位小數的美元字串表示 ("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)。系統每兩秒將這些消息交給網路處理,每個帳戶每分鐘最多處理 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

機器可讀檔案

群發簡訊 API 參考 | BulkSMSAPI 文件