• 覆盖 228 个目的地
  • 始终无需 KYC
  • 支持 Bitcoin、Monero、USDT 等 7 种币种

API阅读约 3 分钟

批量发送:部分拒绝如何运作

一个错误号码不该拖垮一千条消息的批次。批量端点如何验证每条消息、响应包含什么,以及如何处理被拒绝的消息。

SMSMeteor API 团队发布于 2026年9月21日,更新于

真实的联系人名单从来都不干净。一千个号码的批次中,几乎总会有输错的号码、固定电话,或任何人都无法路由的目的地。“全有或全无”的批量端点,会把其中每一个问题都变成一次失败的请求,以及客户端的一个重试循环。SMSMeteor 的批量端点则不同:它接受能够发送的消息,并逐项告诉你哪些被拒绝以及原因。

契约

POST /v1/messages/batch 最多接受 每次 API 请求最多 1,000 条消息,每条消息都有自己的 to 和 text,以及可选的 from 和 reference。from、campaign、send_at、window 和 pace 等顶层字段,适用于所有未覆盖这些字段的消息。随后进行两个层级的验证:

  • 如果请求本身格式错误,例如 JSON 无效或项目数超过上限,整个请求都会被拒绝并返回错误,不会有任何消息进入队列。
  • 如果请求有效但部分消息无效,这些消息会作为已拒绝项连同各自的错误一起返回,所有有效消息则进入队列。

响应包含什么

响应会报告已接受和已拒绝的消息数量、已接受消息的总价,以及附带各自状态的消息列表:

JSON
{
  "batch_id": "bat_3Hq9Zr",
  "accepted": 2, "rejected": 1,
  "total_price": "0.0326", "currency": "USD",
  "messages": [
    { "id": "msg_9Kd2fQ", "to": "+14155550142", "status": "queued" },
    { "id": "msg_9Kd2fR", "to": "+447400123456", "status": "queued" },
    { "to": "+44 74", "status": "rejected", "error": "invalid_number" }
  ]
}

确切字段请参阅 API 参考和 OpenAPI 文件。

项目为何被拒绝

  • 号码不是其所属国家的有效 E.164 号码。
  • 该目的地不在我们的路由范围内。
  • 文本超过 每条消息最多 6 个分段。
  • 内容被执行可接受使用政策的过滤器拒绝。

被拒绝的消息绝不计费,也绝不会到达运营商。它们会与群发任务一起列在报告中,便于你从源头修正,而不是只处理表面症状。

重试而不重复发送

你的服务器和我们的服务器之间的网络会出故障。如果批量请求超时,你无法知道它是否已被处理。请为每个批次发送 Idempotency-Key 标头:使用相同的键值重试时,会返回原始结果,而不会再次将这些消息加入队列。请使用能够标识业务操作的键值,例如群发任务和分块编号,而不是每次尝试时随机生成的值。

吞吐量

API 允许 每个密钥每秒 50 次请求,一个批次计为一次请求。因此,把大型名单拆成每批最多 每次 API 请求最多 1,000 条消息 的批次发送是最快的提交方式;至于发送节奏,用 pace 参数(按每分钟或分摊到若干小时)来控制,比在你自己的代码里使用休眠更好。

仍要在上游清理

部分拒绝是一张安全网,而不是名单清理工具。发送前请将号码规范化为 E.164 格式,删除重复号码,并去掉在以往群发任务中返回为未知号码的号码。控制面板中的导入器会对文件执行这些操作,并报告删除了哪些内容;联系人名单准备指南逐一说明了每个步骤。

批量集成检查清单

  1. 将名单拆分为每批最多 每次 API 请求最多 1,000 条消息 的批次。
  2. 每个分块都带上稳定的 Idempotency-Key 发送。
  3. 将返回的消息 ID 与你自己的 reference 值一起保存。
  4. 记录被拒绝的项目及其错误,并修正源数据。
  5. 使用 pace 和 window,而不是在客户端控制时间。
使用本文介绍的产品开始发送。一个电子邮箱地址即可开户。费率公开,支持加密货币付款。
开始发送