批量端点在一个 API 请求中接受多条各有收件人和正文的消息,并逐条返回结果,使一个无效行不会让整个发送失败。
把一次群发拆成一万个单条请求来发送很慢,而且远在发完之前就会撞上速率限制。批量端点在一次调用中接收多条消息:顶部是共享的默认值,例如发件人、任务标签、发送时间安排和发送速度;下面是各条消息,每条都有自己的收件人、正文以及任何覆盖设置。
验证分两个层面进行。格式错误的请求(JSON 损坏或缺少消息列表)会被整体拒绝,不会有任何消息进入队列。格式正确的请求则逐条判定:有效消息被接受并进入队列;无效消息(前缀不受支持,或号码不是 E.164 格式)则会被拒绝,并在同一列表中连同各自的错误返回。因此,请求返回成功状态只表示批次已被处理,而不表示每条消息都被接受,响应必须逐项阅读。为批次搭配幂等密钥,可以防止超时后的重试让同一批次两次进入队列。
示例
假设一家诊所在一个批次中发送三条提醒。其中两个号码有效;第三个号码的前缀没有任何路由提供服务。响应报告两条已接受并附有消息 ID,一条被拒绝并附有错误。诊所修正第三个号码后单独发送,而不是重发整个批次,否则前两条就会重复。
常见错误
- 看到成功响应就以为“全部已发送”,而不检查逐条结果。
- 部分消息被拒绝后重发整个批次。
- 把紧急的验证码与限速发送的慢速群发放在同一个批次中。
在 SMSMeteor:POST /v1/messages/batch 每个请求最多接受 1,000 条消息。批次级别的 from、campaign、send_at、window 和 pace(per_minute 或 over_hours)适用于所有未自行覆盖这些设置的消息。格式错误的请求会被整体拒绝;无效条目会作为被拒绝项连同错误返回,且绝不计费,有效条目则进入队列。响应包含 batch_id、accepted、rejected、total_price 和 messages[],一个批次在速率限制中只算一个请求。请参阅批量接口参考和拒绝项如何列出。
