開始使用
群發簡訊 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"
}'// 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
}訊息傳遞流程
已接受的消息會進入 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 |
機器可讀檔案
- OpenAPI 3.1規格(供代碼生成器與API客戶端使用)
- llms-full.txt:完整參考文件(純文字格式)
- 所有文件頁面皆提供Markdown格式,例如/en/docs/webhooks.md