跳到正文

短信

短信发送、OTP 与验证,以及投递状态。

1. 概览

基础路径: https://api.infrai.cc/v1/sms
鉴权头: Authorization: Bearer $INFRAI_API_KEY
bash
# Call any /v1/sms capability over raw HTTP — no SDK to install.
# curl:
curl https://api.infrai.cc/v1/sms/... \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json"

2. 方法 (23)

2.1sms.send

POST /v1/sms/send

发送短信;支持模板。

参数

名称类型必填说明
tostring
必填
E.164 格式的收件手机号。
bodystring可选短信文本。
fromstring可选发件标识或号码。
template_idstring可选用于渲染的模板 id(替代正文)。
vendorstring可选固定使用某个供应商,而非自动路由。
idempotency_keystring可选可选去重 key;相同重试将返回同一结果。

返回

SmsRecord { sms_id, to, state, vendor, segments, created_at }
名称类型说明
message_idstringmessage的唯一标识符
pattern: ^sms_[A-Za-z0-9]{20,}$
state"queued" | "sending" | "sent" | "delivered" | "failed" | "deferred" | "expired" | "cancelled" | "auto_suppressed"当前生命周期状态
vendorstring处理此请求的供应商
segmentsinteger长短信分片计费数。
≥ 1
cost_usdnumber | null本次操作费用(美元)
≥ 0
created_atstring资源创建时间(ISO 8601)
format: date-time

示例

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/sms/send \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "sample"}'

2.2sms.otp

POST /v1/sms/otp

向手机号发送一次性验证码。

参数

名称类型必填说明
tostring
必填
E.164 格式的收件手机号。
e.g. +15555550100

返回

{ request_id, expires_at }
名称类型说明
message_idstringmessage的唯一标识符
pattern: ^sms_[A-Za-z0-9]{20,}$
state"queued" | "sending" | "sent" | "delivered" | "failed" | "deferred" | "expired" | "cancelled" | "auto_suppressed"当前生命周期状态
vendorstring处理此请求的供应商
segmentsinteger长短信分片计费数。
≥ 1
cost_usdnumber | null本次操作费用(美元)
≥ 0
created_atstring资源创建时间(ISO 8601)
format: date-time

示例

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/sms/otp \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+15555550100"}'

2.3sms.verify

POST /v1/sms/verify

校验一次性验证码。

参数

名称类型必填说明
tostring
必填
E.164 格式的收件手机号。
codestring
必填
要校验的一次性验证码。

返回

{ valid: boolean }
名称类型说明
verifiedboolean验证是否成功
reason"verified" | "no_code_issued" | "expired" | "too_many_attempts" | "mismatch"结果原因:成功时为 "verified";否则为验证失败的原因
tostring被检查的电话号码

示例

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/sms/verify \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "sample", "code": "123456"}'

2.4sms.status

GET /v1/sms/status/{id}

获取短信的投递状态。

参数

名称类型必填说明
idstring
必填
短信记录 id。

返回

SmsRecord
名称类型说明
idstring消息 ID(send 返回如 "sms_…");存档以 "id" 字段存储。
statusstring生命周期状态:SmsState 枚举之一,ID 未知时为 "not_found"。
channel"sms" | "email" | null该能力始终为 "sms"。
account_idstring | null拥有此资源的账户标识
toany发送时提供的收件人。
vendorstring | null处理发送的供应商;未找到时为 null。
vendor_message_idstring | null上游供应商分配的消息标识符
created_atstring | null资源创建时间(ISO 8601)
format: date-time
foundbooleanID 解析到存档消息时为 true;未匹配时为 false。(未匹配场景应在 SMS_MESSAGE_NOT_FOUND 就绪后抛出带类型的 404——参见模块注释。)
state"queued" | "sending" | "sent" | "delivered" | "failed" | "deferred" | "expired" | "cancelled" | "auto_suppressed"当前生命周期状态
attemptinteger | null当前尝试次数(重试相关)
≥ 0
last_eventstring | null最近事件描述
delivered_atstring | nullISO 8601 时间戳:the message was delivered(ISO 8601)
format: date-time
failed_reasonstring | null如果操作失败,失败原因

示例

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/sms/status/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.5sms.batch.send

POST /v1/sms/batch/send

异构批量发送:每条为完整短信请求,整批共用一个幂等键,按条计费不重复。

参数

名称类型必填说明
messagesSmsSendRequest[]
必填
短信请求数组,最多 100 条,每条为完整的发送请求。
1–100 items
idempotency_keystring可选整批共用的去重键;相同重试返回相同结果。

返回

SmsBatchSendResult { results: SmsSendResult[] }
名称类型说明
resultsobject[]individual results from a batch operation列表
results[].indexinteger在请求 messages 数组中的位置。
≥ 0
results[].resultobject | null此项成功时的发送结果。
results[].result.message_idstringmessage的唯一标识符
pattern: ^sms_[A-Za-z0-9]{20,}$
results[].result.state"queued" | "sending" | "sent" | "delivered" | "failed" | "deferred" | "expired" | "cancelled" | "auto_suppressed"此资源当前的生命周期状态
results[].result.vendorstring处理此请求的供应商
results[].result.segmentsinteger长短信分片计费数。
≥ 1
results[].result.cost_usdnumber | null此操作成本(美元)
≥ 0
results[].result.created_atstring此资源创建的 ISO 8601 时间戳
format: date-time
results[].errorobject | null此项失败时的错误;result 为 null。
results[].error.codestring来自 registry.yaml 的稳定标识符。
results[].error.http_statusintegerWebhook 投递尝试的 HTTP 状态码
400–599
results[].error.messagestring可读提示。
results[].error.docs_urlstring此错误码的文档 URL
format: uri
results[].error.code_detailstring子分类(如钱包上限原因)。
results[].error.retryableboolean错误是否可重试
results[].error.retry_after_msinteger建议重试延迟(毫秒)
≥ 0
results[].error.paramstring验证失败的参数(如适用)。
results[].error.trace_idstring分布式追踪标识符
results[].error.request_idstring服务端分配的追踪请求标识符

示例

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/sms/batch/send \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"to": "sample"}]}'

2.6sms.cancel

POST /v1/sms/cancel/{id}

取消尚未下发的已排程或排队中短信。

参数

名称类型必填说明
idstring
必填
要取消的短信消息 ID。

返回

SmsCancelResult { message_id, cancelled, state }
名称类型说明
message_idstringmessage的唯一标识符
pattern: ^sms_[A-Za-z0-9]{20,}$
cancelledboolean资源是否已成功取消
state"queued" | "sending" | "sent" | "delivered" | "failed" | "deferred" | "expired" | "cancelled" | "auto_suppressed"当前生命周期状态

示例

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/sms/cancel/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message_id": "hello"}'

2.7sms.events

GET /v1/sms/events/{id}

读取单条短信的投递事件时间线。

参数

名称类型必填说明
idstring
必填
短信消息 ID。
cursorstring可选分页游标,从上一页的 next_cursor 取得。
limitnumber可选单页返回的最大条数。

返回

SmsEventList { items: SmsEvent[], next_cursor }
名称类型说明
itemsobject[]本页结果条目数组
items[].type"queued" | "sending" | "sent" | "delivered" | "failed" | "deferred" | "expired" | "cancelled" | "auto_suppressed" | "delivery_receipt" | "inbound"资源类型标识
items[].atstring事件的 ISO 8601 时间戳
format: date-time
items[].recipientstringE.164 格式电话号码。
items[].message_idstring | nullmessage的唯一标识符
pattern: ^sms_[A-Za-z0-9]{20,}$
items[].metaobject | null事件的附加元数据
next_cursorstring | null获取下一页的不透明游标;null 或不存在表示最后一页

示例

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/sms/events/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.8sms.inbound.list

GET /v1/sms/inbound/list

分页列出在已注册发送号上收到的入站(回复)短信。

参数

名称类型必填说明
cursorstring可选分页游标,从上一页的 next_cursor 取得。
limitnumber可选单页返回的最大条数。

返回

SmsListResult { items, next_cursor }
名称类型说明
itemsobject[]本页结果条目数组
items[].type"queued" | "sending" | "sent" | "delivered" | "failed" | "deferred" | "expired" | "cancelled" | "auto_suppressed" | "delivery_receipt" | "inbound"资源类型标识
items[].atstring事件的 ISO 8601 时间戳
format: date-time
items[].recipientstringE.164 格式电话号码。
items[].message_idstring | nullmessage的唯一标识符
pattern: ^sms_[A-Za-z0-9]{20,}$
items[].metaobject | null事件的附加元数据
next_cursorstring | null获取下一页的不透明游标;null 或不存在表示最后一页

示例

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/sms/inbound/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.9sms.resend

POST /v1/sms/resend/{id}

重新下发短信,可选仅重试失败的收件人。

参数

名称类型必填说明
message_idstring
必填
要重发的原短信消息 ID。
pattern: ^sms_[A-Za-z0-9]{20,}$
only_failedboolean可选为 true 时仅重试投递失败的收件人。
default: true
idempotency_keystring可选去重键;相同重试返回相同结果。

返回

SmsBatchSendResult { results }
名称类型说明
message_idstringmessage的唯一标识符
pattern: ^sms_[A-Za-z0-9]{20,}$
state"queued" | "sending" | "sent" | "delivered" | "failed" | "deferred" | "expired" | "cancelled" | "auto_suppressed"当前生命周期状态
vendorstring处理此请求的供应商
segmentsinteger长短信分片计费数。
≥ 1
cost_usdnumber | null本次操作费用(美元)
≥ 0
created_atstring资源创建时间(ISO 8601)
format: date-time

示例

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/sms/resend/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message_id": "hello"}'

2.10sms.sender.register

POST /v1/sms/sender/register

注册发送号码以供验证。

参数

名称类型必填说明
phone_numberstring
必填
要注册的发送号码(E.164 格式)。
regionstring
必填
发送号码所属区域,如 western、china。
methods("otp" | "voice" | "dns")[]可选可用的验证方式列表。
idempotency_keystring可选去重键;相同重试返回相同结果。

返回

SenderVerification { sender_id, phone_number, region, state, methods, created_at }
名称类型说明
sender_idstringsender的唯一标识符
phone_numberstringE.164 格式。
regionstringISO-3166-1 alpha-2(参见 SmsCountryCode)。
state"pending" | "verified" | "failed"当前生命周期状态
methods("otp" | "voice" | "dns")[]发送号使用的验证方式
created_atstring | null资源创建时间(ISO 8601)
format: date-time

示例

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/sms/sender/register \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+15555550100", "region": "sample"}'

2.11sms.sender.get

GET /v1/sms/sender/get/{id}

获取单个已注册发送号的详情。

参数

名称类型必填说明
idstring
必填
发送号 ID。

返回

SenderVerification
名称类型说明
sender_idstringsender的唯一标识符
phone_numberstringE.164 格式。
regionstringISO-3166-1 alpha-2(参见 SmsCountryCode)。
state"pending" | "verified" | "failed"当前生命周期状态
methods("otp" | "voice" | "dns")[]发送号使用的验证方式
created_atstring | null资源创建时间(ISO 8601)
format: date-time

示例

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/sms/sender/get/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.12sms.sender.list

GET /v1/sms/sender/list

分页列出已注册的发送号。

参数

名称类型必填说明
cursorstring可选分页游标,从上一页的 next_cursor 取得。
limitnumber可选单页返回的最大条数。

返回

SmsSenderListResult { items, next_cursor }
名称类型说明
itemsobject[]本页结果条目数组
items[].sender_idstringsender的唯一标识符
items[].phone_numberstringE.164 格式。
items[].regionstringISO-3166-1 alpha-2(参见 SmsCountryCode)。
items[].state"pending" | "verified" | "failed"此资源当前的生命周期状态
items[].methods("otp" | "voice" | "dns")[]发送号使用的验证方式
items[].created_atstring | null此资源创建的 ISO 8601 时间戳
format: date-time
countintegeritems in this page数量
≥ 0
next_cursorstring | null获取下一页的不透明游标;null 或不存在表示最后一页

示例

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/sms/sender/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.13sms.sender.delete

DELETE /v1/sms/sender/delete/{id}

删除一个已注册的发送号。

参数

名称类型必填说明
idstring
必填
要删除的发送号 ID。
idempotency_keystring可选去重键;相同重试返回相同结果。

返回

SmsDeleteResult { deleted }
名称类型说明
sender_idstring | null已删除的发送号标识符
deletedboolean发送号是否已删除
foundboolean是否存在此 ID 的发送号

示例

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X DELETE https://api.infrai.cc/v1/sms/sender/delete/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.14sms.signature.create

POST /v1/sms/signature/create

创建短信签名(中国发送必需)并提交审核。

参数

名称类型必填说明
namestring
必填
签名内容文本。
type"company" | "app" | "website" | "public_account" | "store" | "other"可选签名类型,如 enterprise、individual。
default: "company"
proof_urlstring可选资质证明文件的 URL。
format: uri
remarkstring可选提交审核时的备注说明。
vendorstring可选固定使用某个供应商,而非自动路由。

返回

SmsSignature { signature_id, text, type, review_state, reject_reason, vendor, created_at }
名称类型说明
signature_idstringSMS signature的唯一标识符
namestring显示为【签名】前缀的签名文本。
type"company" | "app" | "website" | "public_account" | "store" | "other"签名场景(中国供应商签名来源)。
default: "company"
review_state"pending" | "approved" | "rejected" | "n/a"中国签名始终以 "pending" 审核状态开始;非中国地区为 "n/a"。
default: "pending"
review_reasonstring | null审核状态为拒绝时供应商的审核备注。
proof_urlstring | null提交给中国供应商的资质证明文档 URL。
vendor_sign_idstring | null供应商分配的签名 ID(如 Tencent SignId / Aliyun SignName),真实提交后记录。
created_atstring资源创建时间(ISO 8601)
format: date-time
updated_atstring | null资源最后更新时间(ISO 8601)
format: date-time
foundboolean在 sms.signature.get 上存在;签名存在时为 true。(缺失签名应在 SMS_SIGNATURE_NOT_FOUND 就绪后抛出带类型的 404——参见模块注释。)

示例

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/sms/signature/create \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "example"}'

2.15sms.signature.get

GET /v1/sms/signature/get/{id}

读取单个短信签名及其审核状态。

参数

名称类型必填说明
idstring
必填
签名 ID。

返回

SmsSignature
名称类型说明
signature_idstringSMS signature的唯一标识符
namestring显示为【签名】前缀的签名文本。
type"company" | "app" | "website" | "public_account" | "store" | "other"签名场景(中国供应商签名来源)。
default: "company"
review_state"pending" | "approved" | "rejected" | "n/a"中国签名始终以 "pending" 审核状态开始;非中国地区为 "n/a"。
default: "pending"
review_reasonstring | null审核状态为拒绝时供应商的审核备注。
proof_urlstring | null提交给中国供应商的资质证明文档 URL。
vendor_sign_idstring | null供应商分配的签名 ID(如 Tencent SignId / Aliyun SignName),真实提交后记录。
created_atstring资源创建时间(ISO 8601)
format: date-time
updated_atstring | null资源最后更新时间(ISO 8601)
format: date-time
foundboolean在 sms.signature.get 上存在;签名存在时为 true。(缺失签名应在 SMS_SIGNATURE_NOT_FOUND 就绪后抛出带类型的 404——参见模块注释。)

示例

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/sms/signature/get/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.16sms.signature.list

GET /v1/sms/signature/list

分页列出短信签名。

参数

名称类型必填说明
cursorstring可选分页游标,从上一页的 next_cursor 取得。
limitnumber可选单页返回的最大条数。

返回

SmsSignatureListResult { items, next_cursor }
名称类型说明
itemsobject[]本页结果条目数组
items[].signature_idstringSMS signature的唯一标识符
items[].namestring显示为【签名】前缀的签名文本。
items[].type"company" | "app" | "website" | "public_account" | "store" | "other"签名场景(中国供应商签名来源)。
default: "company"
items[].review_state"pending" | "approved" | "rejected" | "n/a"中国签名始终以 "pending" 审核状态开始;非中国地区为 "n/a"。
default: "pending"
items[].review_reasonstring | null审核状态为拒绝时供应商的审核备注。
items[].proof_urlstring | null提交给中国供应商的资质证明文档 URL。
items[].vendor_sign_idstring | null供应商分配的签名 ID(如 Tencent SignId / Aliyun SignName),真实提交后记录。
items[].created_atstring此资源创建的 ISO 8601 时间戳
format: date-time
items[].updated_atstring | null此资源最后更新的 ISO 8601 时间戳
format: date-time
items[].foundboolean在 sms.signature.get 上存在;签名存在时为 true。(缺失签名应在 SMS_SIGNATURE_NOT_FOUND 就绪后抛出带类型的 404——参见模块注释。)
next_cursorstring | null获取下一页的不透明游标;null 或不存在表示最后一页
countinteger跨所有页的总条目数
≥ 0

示例

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/sms/signature/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.17sms.signature.delete

DELETE /v1/sms/signature/delete/{id}

删除一个短信签名。

参数

名称类型必填说明
idstring
必填
要删除的签名 ID。
idempotency_keystring可选去重键;相同重试返回相同结果。

返回

SmsDeleteResult { deleted }
名称类型说明
signature_idstring | null已删除的签名标识符
deletedboolean签名是否已删除
foundboolean是否存在此 ID 的签名

示例

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X DELETE https://api.infrai.cc/v1/sms/signature/delete/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.18sms.template.create

POST /v1/sms/template/create

创建带命名变量的可复用短信模板。

参数

名称类型必填说明
namestring
必填
模板名称。
bodystring
必填
模板正文,可含 {变量} 占位符。
localestring可选模板语言区域,如 en、zh。
default: "en"
variablesstring[]可选模板中使用的变量名列表。
vendorstring可选固定使用某个供应商,而非自动路由。

返回

SmsTemplate { template_id, name, body, locale, variables, review_state, created_at }
名称类型说明
template_idstring用于渲染的模板标识符
namestring资源的可读名称
bodystring消息的纯文本正文
localestring模板的语言代码(如 en-US、zh-CN)
default: "en"
variablesstring[]模板变量定义
review_state"pending" | "approved" | "rejected" | "n/a"中国供应商必填;其他情况为 n/a。
default: "n/a"
review_reasonstring | null审核状态为拒绝时供应商的审核备注。
vendor_template_idstring | null供应商分配的模板 ID,真实提交后记录(通过 query_review_state 轮询)。
created_atstring资源创建时间(ISO 8601)
format: date-time
updated_atstring | null资源最后更新时间(ISO 8601)
format: date-time
foundboolean在 sms.template.get 上存在;模板存在时为 true。(缺失模板应在 SMS_TEMPLATE_NOT_FOUND 就绪后抛出带类型的 404——参见模块注释。)

示例

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/sms/template/create \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "example", "body": "hello"}'

2.19sms.template.delete

DELETE /v1/sms/template/delete/{id}

删除一个短信模板。

参数

名称类型必填说明
idstring
必填
要删除的模板 ID。
idempotency_keystring可选去重键;相同重试返回相同结果。

返回

SmsDeleteResult { deleted }
名称类型说明
template_idstring | null已删除的模板标识符
deletedboolean模板是否已删除
foundboolean是否存在此 ID 的模板

示例

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X DELETE https://api.infrai.cc/v1/sms/template/delete/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.20sms.suppression.add

POST /v1/sms/suppression/add

将号码加入抑制(免打扰)列表。

参数

名称类型必填说明
phonestring
必填
要抑制的电话号码(E.164 格式)。
reason"user_request" | "stop_reply" | "carrier_block" | "invalid" | "manual"可选抑制原因,如 opt_out、complaint。
default: "manual"
scope"account" | "sender"可选抑制范围,如 account、global。
default: "account"
sender_scopestring可选限定到某发送号的抑制范围。
notesstring可选内部备注说明。
idempotency_keystring可选去重键;相同重试返回相同结果。

返回

SuppressionRecord { phone, scope, reason, created_at }
名称类型说明
phonestringE.164 格式电话号码。
reason"user_request" | "stop_reply" | "carrier_block" | "invalid" | "manual"当前状态或操作原因
added_atstring资源添加时间(ISO 8601)
format: date-time
scope"account" | "sender"此资源的适用范围
sender_scopestring | null当 scope=sender 时,sender_id。
last_attempt_atstring | null最近一次被阻止发送尝试的 ISO 8601 时间戳(如有)。
format: date-time
attempt_count_blockedinteger迄今此抑制条目阻止的发送尝试次数。
≥ 0
notesstring | null添加条目时附加的自由格式备注。

示例

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/sms/suppression/add \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+15555550100"}'

2.21sms.suppression.check

POST /v1/sms/suppression/check

发送前检查号码是否已被抑制。

参数

名称类型必填说明
phonestring
必填
要检查的电话号码(E.164 格式)。
scope"account" | "sender"可选检查的抑制范围,如 account、global。
default: "account"
sender_scopestring可选限定到某发送号的检查范围。

返回

SmsSuppressionCheckResult { suppressed, record }
名称类型说明
phonestring被检查的 E.164 电话号码。
suppressedboolean该地址当前是否被抑制
reason"user_request" | "stop_reply" | "carrier_block" | "invalid" | "manual"抑制原因;仅在 suppressed=true 时存在
added_atstring条目添加的 ISO 8601 时间戳;仅在 suppressed=true 时存在
format: date-time
scope"account" | "sender"匹配条目的范围;仅在 suppressed=true 时存在
sender_scopestring | null当 scope=sender 时的 sender_id;仅在 suppressed=true 时存在
last_attempt_atstring | null最近一次被阻止发送尝试的 ISO 8601 时间戳(如有)
format: date-time
attempt_count_blockedinteger迄今此抑制条目阻止的发送尝试次数;仅在 suppressed=true 时存在
≥ 0
notesstring | null添加条目时附加的自由格式备注

示例

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/sms/suppression/check \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+15555550100"}'

2.22sms.suppression.list

GET /v1/sms/suppression/list

分页列出被抑制的号码。

参数

名称类型必填说明
cursorstring可选分页游标,从上一页的 next_cursor 取得。
limitnumber可选单页返回的最大条数。

返回

SmsSuppressionListResult { items, total_count, next_cursor }
名称类型说明
itemsobject[]本页结果条目数组
items[].phonestringE.164 格式电话号码。
items[].reason"user_request" | "stop_reply" | "carrier_block" | "invalid" | "manual"当前状态或动作的原因
items[].added_atstring此资源添加的 ISO 8601 时间戳
format: date-time
items[].scope"account" | "sender"此资源的适用范围
items[].sender_scopestring | null当 scope=sender 时,sender_id。
items[].last_attempt_atstring | null最近一次被阻止发送尝试的 ISO 8601 时间戳(如有)。
format: date-time
items[].attempt_count_blockedinteger迄今此抑制条目阻止的发送尝试次数。
≥ 0
items[].notesstring | null添加条目时附加的自由格式备注。
countinteger | null所有页的条目总数
≥ 0
total_countinteger | null跨所有页的总条目数
≥ 0
next_cursorstring | null获取下一页的不透明游标;null 或不存在表示最后一页

示例

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/sms/suppression/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.23sms.suppression.delete

POST /v1/sms/suppression/delete

从抑制列表移除号码以恢复发送。

参数

名称类型必填说明
phonestring
必填
要移除的电话号码(E.164 格式)。
scope"account" | "sender"可选移除的抑制范围,如 account、global。
default: "account"
sender_scopestring可选限定到某发送号的移除范围。
idempotency_keystring可选去重键;相同重试返回相同结果。

返回

SmsSuppressionRemoveResult { phone, removed }
名称类型说明
phonestring目标 E.164 电话号码。
deletedboolean资源是否已成功移除
foundboolean是否存在匹配的条目

示例

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/sms/suppression/delete \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+15555550100"}'
高级:指定 vendor

默认情况下 infrai 会把每次调用智能路由到最佳可用供应商——无需自己挑选 vendor。作为高级逃生口,本能力支持可选的 vendor 入参以锁定某个供应商。本能力当前所有可用 vendor 可通过该能力 id 对应的 discovery 端点实时获取——参见 discovery API

GET /v1/discovery/{capability}

sms.send

sms.signature.create

sms.template.create

3. 全部能力

本模块全部已路由能力——完整的对外 REST 契约。上方方法是带讲解的入门示例,此表是完整参考。

sms.batch.sendPOST /v1/sms/batch/send

Send a heterogeneous batch of SMS (each a full request) under one idempotency key, billed per message.

参数 (2)
名称类型必填说明
messagesobject[]必填Up to 100 SmsSendRequest items.
1–100 items
idempotency_keystring | null可选Client-provided idempotency key; prevents duplicate execution on retry
sms.cancelPOST /v1/sms/cancel/{id}

Cancel a scheduled or queued SMS that has not yet been dispatched.

参数 (3)
名称类型必填说明
idstring必填Path parameter.
message_idstring必填Id of the SMS message to cancel.
pattern: ^sms_[A-Za-z0-9]{20,}$
idempotency_keystring | null可选Client-provided idempotency key; prevents duplicate execution on retry
sms.eventsGET /v1/sms/events/{id}

Retrieve the delivery event timeline for a single SMS message.

参数 (1)
名称类型必填说明
idstring必填Path parameter.
sms.inbound.listGET /v1/sms/inbound/list

List inbound (reply) SMS received on registered sender numbers, with pagination.

无请求参数。

sms.otpPOST /v1/sms/otp

Send a one-time passcode via SMS with gateway-managed OTP lifecycle.

参数 (4)
名称类型必填说明
tostring必填Destination phone number (E.164).
e.g. +15555550100
phonestring | null可选Legacy alias for to.
templatestring | null可选Message template containing {code}; defaults to 'Your verification code is {code}'.
idempotency_keystring | null可选Client-provided idempotency key; prevents duplicate execution on retry
sms.resendPOST /v1/sms/resend/{id}

Resend an SMS, optionally retrying only the failed recipients.

参数 (4)
名称类型必填说明
idstring必填Path parameter.
message_idstring必填Unique identifier for this message
pattern: ^sms_[A-Za-z0-9]{20,}$
only_failedboolean可选Re-dispatch only failed recipients; false resends the whole original recipient set.
default: true
idempotency_keystring | null可选Client-provided idempotency key; prevents duplicate execution on retry
sms.sendPOST /v1/sms/send

Send an SMS message to one or more recipients (idempotent).

参数 (12)
名称类型必填说明
tostring | string[]必填E.164 phone number or array of.
bodystring | null可选Plain text body of the message
fromstring | null可选Sender ID / phone number; required for verified_sender mode.
template_idstring | null可选Identifier of the template used for rendering
template_varsobject | null可选Variables to substitute in the template
vendorstring | null可选Pin to a specific vendor.
mode"default_vendor" | "verified_sender"可选Delivery mode or operation mode
default: "default_vendor"
scheduled_atstring | null可选ISO 8601 timestamp when the resource is scheduled to activate
format: date-time
idempotency_keystring | null可选Client-provided idempotency key; prevents duplicate execution on retry
tagsstring[]可选Tags for categorization and filtering
route_class"transactional" | "otp" | "marketing"可选SMS route class for delivery optimization
default: "transactional"
opt_in_proof_urlstring | null可选Required when route_class=marketing.
format: uri
sms.sender.deleteDELETE /v1/sms/sender/delete/{id}

Delete a registered sender number.

参数 (1)
名称类型必填说明
idstring必填Path parameter.
sms.sender.getGET /v1/sms/sender/get/{id}

Retrieve details of a single registered sender number.

参数 (1)
名称类型必填说明
idstring必填Path parameter.
sms.sender.listGET /v1/sms/sender/list

List registered sender numbers with pagination.

无请求参数。

sms.sender.registerPOST /v1/sms/sender/register

Register a sender number for verification.

参数 (4)
名称类型必填说明
phone_numberstring必填E.164 phone number or alphanumeric sender ID.
regionstring必填ISO-3166-1 alpha-2 (see SmsCountryCode).
methods("otp" | "voice" | "dns")[]可选Verification methods to attempt; vendor/region picks default if omitted.
idempotency_keystring | null可选Client-provided idempotency key; prevents duplicate execution on retry
sms.signature.createPOST /v1/sms/signature/create

Create an SMS signature (required for China delivery) and submit it for review.

参数 (5)
名称类型必填说明
namestring必填Signature text shown as the 【签名】 prefix, e.g. 'Acme'.
type"company" | "app" | "website" | "public_account" | "store" | "other"可选Signature scene (China vendor 签名来源).
default: "company"
proof_urlstring | null可选URL to the authorization letter / business-license image required for brand review.
format: uri
remarkstring | null可选Note shown to the vendor reviewer.
vendorstring | null可选Pin the vendor to register at; otherwise the gateway picks per region.
sms.signature.deleteDELETE /v1/sms/signature/delete/{id}

Delete a registered SMS signature (China-route vendor pre-config); sends referencing it will be rejected.

参数 (1)
名称类型必填说明
idstring必填Path parameter.
sms.signature.getGET /v1/sms/signature/get/{id}

Retrieve a single SMS signature and its review status.

参数 (1)
名称类型必填说明
idstring必填Path parameter.
sms.signature.listGET /v1/sms/signature/list

List SMS signatures with pagination.

无请求参数。

sms.statusGET /v1/sms/status/{id}

Query the delivery status of an SMS message by ID.

参数 (1)
名称类型必填说明
idstring必填Path parameter.
sms.suppression.addPOST /v1/sms/suppression/add

Add a phone number to the suppression (do-not-contact) list.

参数 (6)
名称类型必填说明
phonestring必填E.164 phone.
reason"user_request" | "stop_reply" | "carrier_block" | "invalid" | "manual"可选Reason for the current state or action
default: "manual"
scope"account" | "sender"可选Scope of applicability for this resource
default: "account"
sender_scopestring | null可选Required when scope=sender: the sender_id the suppression is bound to.
notesstring | null可选Free-text notes about this suppression
idempotency_keystring | null可选Client-provided idempotency key; prevents duplicate execution on retry
sms.suppression.checkPOST /v1/sms/suppression/check

Check whether a phone number is suppressed before sending.

参数 (3)
名称类型必填说明
phonestring必填E.164 phone.
scope"account" | "sender"可选Scope of applicability for this resource
default: "account"
sender_scopestring | null可选Required when scope=sender.
sms.suppression.deletePOST /v1/sms/suppression/delete

Remove a number from the suppression list to resume sending.

参数 (4)
名称类型必填说明
phonestring必填E.164 phone.
scope"account" | "sender"可选Scope of applicability for this resource
default: "account"
sender_scopestring | null可选Required when scope=sender.
idempotency_keystring | null可选Client-provided idempotency key; prevents duplicate execution on retry
sms.suppression.listGET /v1/sms/suppression/list

List suppressed phone numbers with pagination.

无请求参数。

sms.template.createPOST /v1/sms/template/create

Create a reusable SMS template with named variables.

参数 (5)
名称类型必填说明
namestring必填Human label for the template.
bodystring必填Template text with double-brace var placeholders (Mustache-subset).
localestring可选zh/cn locales trigger China-vendor review.
default: "en"
variablesstring[]可选Declared placeholder names; inferred from body if omitted.
vendorstring | null可选Pin the vendor to register at; otherwise the gateway picks per region.
sms.template.deleteDELETE /v1/sms/template/delete/{id}

Delete a registered SMS message template (vendor pre-config); sends referencing it will be rejected.

参数 (1)
名称类型必填说明
idstring必填Path parameter.
sms.verifyPOST /v1/sms/verify

Verify a user-submitted SMS one-time passcode.

参数 (5)
名称类型必填说明
tostring必填Phone number the OTP was issued to (E.164).
phonestring | null可选Legacy alias for to.
codestring必填The one-time code to verify.
otpstring | null可选Legacy alias for code.
idempotency_keystring | null可选Client-provided idempotency key; prevents duplicate execution on retry

4. 完整示例

本模块的生产级端到端范例:先一次性配置,再运行业务流程,尽量覆盖本模块的多数 API。

单文件可运行 Python 程序(仅标准库、无 SDK):拷贝后填入 INFRAI_API_KEY 运行,即可按真实业务流逐步体验本模块核心 API——每一步都真实调用并计费,后续步骤复用前一步返回的真实字段。12 行 helper 就是全部集成代码。

python
#!/usr/bin/env python3
"""Infrai · sms — runnable real-app example (single file, zero deps).

Copy this file, set your key, run it: every step is a REAL call to
api.infrai.cc, billed at the real (tiny) per-call price, printing the
live JSON response. Get a key at https://infrai.cc/login (Google/
GitHub sign-in grants $2 free credit); add funds at
https://infrai.cc/billing. No SDK — the 12-line helper below is the
entire integration."""
import json
import os
from urllib import error, request

KEY = os.environ.get("INFRAI_API_KEY") or "ifr_..."  # <- your key
BASE = "https://api.infrai.cc"


# Same raw HTTPS POST/GET as every per-method example on this page —
# wrapped once for reuse. There is nothing else to it: no SDK.
def infrai(method, path, body=None):
    req = request.Request(
        BASE + path, method=method,
        data=json.dumps(body).encode() if body is not None else None,
        headers={"Authorization": f"Bearer {KEY}",
                 "Content-Type": "application/json"})
    try:
        with request.urlopen(req, timeout=60) as r:
            return json.loads(r.read())
    except error.HTTPError as e:
        return json.loads(e.read())


def show(label, resp):
    print(f"\n== {label} ==")
    print(json.dumps(resp, indent=2, ensure_ascii=False))
    return resp


# 1) sms.otp — POST /v1/sms/otp · Send a one-time passcode via SMS with gateway-managed OTP lifecycle.
ask1 = input("Your phone number, intl format (+86...): ").strip()
r1 = show("sms.otp", infrai("POST", "/v1/sms/otp", {"to":ask1}))

# 2) sms.verify — POST /v1/sms/verify · Verify a user-submitted SMS one-time passcode.
ask2 = input("Enter the code you just received: ").strip()
r2 = show("sms.verify", infrai("POST", "/v1/sms/verify", {"to":ask1,"code":ask2}))