发送前须知
使用为您的账户配置的发送号码发送 SMS 或受支持的 MMS。这是生产环境中的操作，可能会联系收件人并产生费用。仅向已获授权的收件人发送获准的消息流量；下方示例中的号码和关联标记均为虚构。
您的账户需要获准发送出站消息，并具备适用的发送方、国家和消息流量权限。直接使用个人／消费者用户凭据不符合此 API 的使用资格。经批准的专用 API 凭据有单独的资格审核流程；移动 P2P 发送方可能还需要额外的 P2P 及美国／加拿大权限。请向 MultiTEL 确认正确的账户配置，不要认为拥有 API 凭据就自动获得了发送任何消息流量的权限。
发送请求
从已启用的 API 账户所允许的源 IP 地址，通过 HTTPS 使用该账户进行身份验证。将凭据保存在服务器端的机密存储中。使用 POST 提交表单编码字段；未提供表单字段或查询字段时，也可提交 JSON 对象。不要将凭据或消息正文放入 URL。
curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
--data-urlencode 'from=12025550123' \
--data-urlencode 'to=12025550124' \
--data-urlencode 'text=Your requested update is ready.' \
--data-urlencode 'reference=order-update-example' \
https://api.multitel.net/v3/sendsms| 字段 | 是否必填 | 含义 |
|---|---|---|
| from | 是 | 为您配置的发送号码，建议使用完整国际号码的数字形式。 |
| to | 是 | 一个接收号码、以逗号分隔的多个接收号码，或 JSON 数组。建议使用完整国际号码的数字形式。群发请求可能因适用的 P2P／国家限制而被拒绝；此 API 并非不受限制的批量发送接口。 |
| text | 发送 SMS 时必填 | UTF-8 编码的消息正文。至少须提供非空正文或媒体内容。请发送实际字符和换行符，而非 HTML 或经过百分号转义的文本。某些运营商处理路径会对字面形式的转义字符串进行规范化。 |
| media | 发送仅含媒体的 MMS 时必填 | 经 Base64 编码的媒体内容，而非 URL 或文件路径。MMS 的可用性、格式和大小取决于所配置的路由。请向 MultiTEL 确认支持的媒体；此处理程序并未规定通用的媒体大小上限。 |
| reference | 建议填写 | 您用于关联请求的标记，会保留在记录和回调中。建议填写，以便排查问题。它不是幂等键。 |
| notifyurl | 否 | 您的 HTTPS 回调接收端。处理程序可在处理后通过 POST 发送初始结果。该接收端必须由您控制，且不得使用内部服务 URL。 |
如使用 JSON 数组，请在 to 中提供真正的数组；不要将 JSON 数组字符串放入表单字段。首次集成测试应采用单一收件人发送。不同路由对群发和 MMS 的支持有所不同，因此使用前请确认所需组合是否受支持。
读取完整结果
仅选取部分字段用于示例；所显示的费用不是报价。
{
"status": {
"code": "200",
"msg": ""
},
"response": {
"sms_log_id_ori": 42,
"to": "12025550124",
"from": "12025550123",
"status": "Success",
"message": "Message queued",
"causecode": 0,
"uniqueid": "fixture-message",
"cost": "$0.0120",
"carrier_fee_usd": "0.0020000000",
"chars": 31,
"parts": 1,
"encoding": "GSM-7",
"permsg": "$0.0120",
"pid": "fixture-reference"
}
}请结合 HTTP 状态、JSON 中的 status.code 以及响应中的 status/message 一并检查。结果代码可能是字符串。请保留 sms_log_id_ori 以及返回的消息／关联标记值，以便支持人员关联查询。旧版 uniqueid 和 pid 的值因路由而异；不要推断其格式，也不要假定它们是客户端幂等令牌。
Success 或 Message queued 通常表示所选路由已受理，而不表示收件人的手机已收到消息。初始回调中的 sent 等状态本身并不能证明最终送达。
分段与费用
请使用SMS 长度分析，在发送前分析完整的最终正文。SMS 价格取决于接收目的地及账户服务；适用的运营商费用按段加收。发送处理路径会将各收件人的价格与适用费用合计，再乘以计算出的 SMS 段数。在此计算中，MMS 请求按一条消息处理。
在旧版响应中，cost 和 permsg 是已格式化的金额字符串。carrier_fee_usd 以 USD 报告运营商费用部分，该费用已包含在计算出的发送总额中；不要重复相加。实际账户价格和路由可用性必须针对您的账户进行核实。此请求并非仅用于查询价格。
经审查的代码会在运营商发送路径成功后扣款，但运营商受理、本地持久化和计费并不属于同一个事务。上游请求被受理后，仍可能发生错误或超时。此接口未提供客户端幂等键：重复使用同一关联标记可能再次发送并再次收费。
本地投递与混合结果
本地托管号码的消息可以被受理（accepted）并进入 MultiTEL 的入站消息流程，无需通过外部运营商发送。对于全部收件人均为本地号码的请求，响应可能包含 accepted、message_id、provider 和 delivery_status。本地受理并不保证收件人配置的转发目的地已成功接收。
如果存在 local_delivery_results 和 partial，请检查这些字段。某个收件人可能显示 accepted 为 true，但其转发结果仍不成功。混合请求中，运营商侧的收件人可能已被受理（accepted），而本地部分失败。不要自动重试整个批次：请先逐一核对各收件人的结果。
在此处理路径中，全部收件人均为本地号码且请求获受理时，报告的出站费用为零，但收件人仍可能产生正常的入站消息费用。不要将出站费用为零理解为保证所有账户均不会被收费。
回调与关联
提供 notifyurl 时，初始回调包含 status 状态封装，以及 message_id、reference、from、to、status、status_text、error_code、timestamp 和 accepted 等响应字段。也可能包含本地处理结果。请保存关联信息，但不要将 API 凭据或不必要的消息内容写入日志。
此处理程序不会在该初始回调中添加签名字段。不要将未经验证的回调作为执行另一项操作的独立授权依据。请查阅您的账户所支持的集成／Webhook 配置，并通过门户记录或支持人员核对不确定的结果。不要假定回调只会到达一次，也不要假定其到达顺序与最终送达顺序一致。
失败与安全恢复
验证失败可能使用 API 代码 403。因账户审批、P2P 或国家政策而拒绝请求时，也可能设置 HTTP 403，并包含机器可读的 response.code。触发速率限制时，可能使用 429 并附带重试信息。策略不可用、发送失败或本地持久化失败时，可能使用 503 或 500；旧版余额不足情况也可能返回 500。
对于 429，请遵循 Retry-After 及任何 response.retry_after 值。对于因账户、发送方、国家或收件人而被拒绝的请求，请先解决原因再重试。如果发生超时或发送结果不明确，请保留请求时间、关联标记和返回的标识符，并在重新发送前查看门户及联系支持人员。仅仅缺少日志记录，并不能证明没有运营商受理该请求。