快速开始
群发短信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)。队列每2秒向网络提交消息,每账户每分钟限1200条,状态转为sent。最终状态为delivered或failed;失败消息立即退款至余额。每个最终状态都会触发带签名的webhook事件
限制概览
| 限制项 | 阈值 |
|---|---|
| 单次API请求接收方上限 | 10,000 |
| 控制台单次活动接收方上限 | 50,000 |
| 单密钥每分钟请求上限 | 600 |
| 单账户每分钟提交至网络的消息上限 | 1,200 |
| 最大文本长度 | 10个分段(GSM-7编码1530字符或UCS-2编码670字符) |
| 预约时间窗口 | 最早2分钟后,最迟45天内 |
| 单事件webhook重试次数 | 10 |
| Idempotency-Key记忆时长 | 24小时 |
| 单账户API密钥数量上限 | 10 |
机器可读文件
- OpenAPI 3.1规范(用于代码生成器和API客户端)
- llms-full.txt:完整文档的纯文本版本
- 所有文档页面的Markdown版本,例如/en/docs/webhooks.md