快速开始

群发短信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)。队列每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

机器可读文件

群发短信API参考 | BulkSMSAPI文档