SMS REST API 让软件通过 HTTPS 和 JSON 发送消息并读取状态,使用标准方法和 URL,无需持久连接或电信协议。
REST 把消息操作映射为普通的 Web 请求。消息、批次和费率等资源都有各自的 URL;HTTP 方法说明要对资源做什么,POST 用于创建,GET 用于读取;正文使用 JSON;结果用 HTTP 状态码表示:2xx 表示成功,4xx 表示请求有问题,5xx 表示服务器端有问题,正文中还会附上机器可读的错误代码。每个请求都是自包含的,并携带自己的凭据,因此任何具备 HTTP 客户端的语言都能完成集成,无需专用库、持久连接或 SMPP 之类的电信协议。
通过 REST 发送 SMS 本质上是异步的。POST 的响应确认消息已被接受、验证并计价;它无法确认送达,因为送达发生在几秒或几小时之后的运营商网络上。状态随后才会到来:通过 Webhook 推送,或再次读取该消息获得。
衡量 SMS API 优劣的特性,要到出错时才会显现出来:幂等密钥确保重试绝不会造成重复发送,此外还有稳定的错误代码、签名 Webhook、速率限制标头、测试模式和公开的 OpenAPI 描述。
示例
假设一家商店用 POST 提交一条订单通知,其中包含 E.164 格式的收件人号码、发件人和正文。响应返回消息 ID、状态 queued、分段数、编码和价格。片刻之后,Webhook 报告消息已变为 sent,不久后又变为 delivered。
常见错误
- 把 2xx 响应当作送达证明。
- 不带幂等密钥就重试超时的 POST。
- 根据错误消息而不是错误代码进行匹配。
- 从浏览器或移动应用中调用 API,这会暴露密钥。
在 SMSMeteor:六个端点共用一个基础 URL https://api.smsmeteor.com/v1:POST /v1/messages 发送一条消息,POST /v1/messages/batch 最多发送 1,000 条,GET /v1/messages/{id} 返回单条消息的状态,GET /v1/messages 以游标分页列出和筛选消息,GET /v1/rates 返回公开费率表,GET /v1/balance 返回余额。密钥是 Bearer 密钥(sk_live_、sk_test_),权限限定为 send、read 或两者兼有。响应会报告 encoding 和 segments,API 从不改写文本。OpenAPI 3.1 描述位于 /docs/openapi.yaml;我们不向账户提供 SMPP。请从快速入门开始。
