短信

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

概览

基础路径: 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"

方法

sms.send

POST /v1/sms/send

发送短信；支持模板与 BYOK 供应商。

参数

名称	类型	必填	说明
`to`	`string`	必填	E.164 格式的收件手机号。
`body`	`string`	可选	短信文本。
`from`	`string`	可选	发件标识或号码。
`template_id`	`string`	可选	用于渲染的模板 id（替代正文）。
`vendor`	`string`	可选	固定使用某个供应商，而非自动路由。
`idempotency_key`	`string`	可选	可选去重 key；相同重试将返回同一结果。

SmsRecord { sms_id, to, state, vendor, segments, created_at }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/sms/send \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+14155550100", "body": "Your code is 123456"}'

sms.otp

POST /v1/sms/otp

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

参数

名称	类型	必填	说明
`to`	`string`	必填	E.164 格式的收件手机号。

{ request_id, expires_at }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/sms/otp \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "..."}'

sms.verify

POST /v1/sms/verify

校验一次性验证码。

参数

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

{ valid: boolean }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/sms/verify \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "...", "code": "..."}'

sms.status

GET /v1/sms/status/{id}

获取短信的投递状态。

参数

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

SmsRecord

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/sms/status/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

sms.batch.send

POST /v1/sms/batch/send

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

参数

名称	类型	必填	说明
`messages`	`SmsSendRequest[]`	必填	短信请求数组，最多 100 条，每条为完整的发送请求。
`idempotency_key`	`string`	可选	整批共用的去重键；相同重试返回相同结果。

SmsBatchSendResult { results: SmsSendResult[] }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

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": []}'

sms.cancel

POST /v1/sms/cancel/{id}

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

参数

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

SmsCancelResult { message_id, cancelled, state }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

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": "..."}'

sms.events

GET /v1/sms/events/{id}

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

参数

名称	类型	必填	说明
`id`	`string`	必填	短信消息 ID。
`cursor`	`string`	可选	分页游标，从上一页的 next_cursor 取得。
`limit`	`number`	可选	单页返回的最大条数。

SmsEventList { items: SmsEvent[], next_cursor }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/sms/events/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

sms.inbound.list

GET /v1/sms/inbound/list

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

参数

名称	类型	必填	说明
`cursor`	`string`	可选	分页游标，从上一页的 next_cursor 取得。
`limit`	`number`	可选	单页返回的最大条数。

SmsListResult { items, next_cursor }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/sms/inbound/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

sms.list

GET /v1/sms/list

分页列出已发送的短信记录。

参数

名称	类型	必填	说明
`cursor`	`string`	可选	分页游标，从上一页的 next_cursor 取得。
`limit`	`number`	可选	单页返回的最大条数。

SmsListResult { items, next_cursor }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/sms/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

sms.lookup

POST /v1/sms/lookup

校验号码并补充运营商、号码类型等信息。

参数

名称	类型	必填	说明
`phone`	`string`	必填	要查询的电话号码（E.164 格式）。
`fields`	`string[]`	可选	需返回的补充字段列表，如 carrier、line_type。

SmsLookupResult { phone, valid, country_code, carrier, line_type, caller_name }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/sms/lookup \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "..."}'

sms.resend

POST /v1/sms/resend/{id}

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

参数

名称	类型	必填	说明
`message_id`	`string`	必填	要重发的原短信消息 ID。
`only_failed`	`boolean`	可选	为 true 时仅重试投递失败的收件人。
`idempotency_key`	`string`	可选	去重键；相同重试返回相同结果。

SmsBatchSendResult { results }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

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": "..."}'

sms.sender.register

POST /v1/sms/sender/register

注册发送号码以供验证。

参数

名称	类型	必填	说明
`phone_number`	`string`	必填	要注册的发送号码（E.164 格式）。
`region`	`string`	必填	发送号码所属区域，如 western、china。
`methods`	`string[]`	可选	可用的验证方式列表。
`idempotency_key`	`string`	可选	去重键；相同重试返回相同结果。

SenderVerification { sender_id, phone_number, region, state, methods, created_at }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

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": "...", "region": "..."}'

sms.sender.verify

POST /v1/sms/sender/verify

用验证码确认已注册的发送号码。

参数

名称	类型	必填	说明
`sender_id`	`string`	必填	待验证的发送号 ID。
`code`	`string`	可选	收到的验证码。
`idempotency_key`	`string`	可选	去重键；相同重试返回相同结果。

SenderVerification { sender_id, phone_number, region, state, methods, created_at }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/sms/sender/verify \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sender_id": "..."}'

sms.sender.get

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

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

参数

名称	类型	必填	说明
`id`	`string`	必填	发送号 ID。

SenderVerification

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/sms/sender/get/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

sms.sender.list

GET /v1/sms/sender/list

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

参数

名称	类型	必填	说明
`cursor`	`string`	可选	分页游标，从上一页的 next_cursor 取得。
`limit`	`number`	可选	单页返回的最大条数。

SmsSenderListResult { items, next_cursor }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/sms/sender/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

sms.sender.delete

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

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

参数

名称	类型	必填	说明
`id`	`string`	必填	要删除的发送号 ID。
`idempotency_key`	`string`	可选	去重键；相同重试返回相同结果。

SmsDeleteResult { deleted }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X DELETE https://api.infrai.cc/v1/sms/sender/delete/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

sms.sender.reputation

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

查询发送号的信誉等级与限流风险。

参数

名称	类型	必填	说明
`id`	`string`	必填	发送号 ID。

SmsSenderReputation { sender_id, tier, complaint_rate_30d, cap, used_today, throttle_risk }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/sms/sender/reputation/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

sms.signature.create

POST /v1/sms/signature/create

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

参数

名称	类型	必填	说明
`name`	`string`	必填	签名内容文本。
`type`	`string`	可选	签名类型，如 enterprise、individual。
`proof_url`	`string`	可选	资质证明文件的 URL。
`remark`	`string`	可选	提交审核时的备注说明。
`vendor`	`string`	可选	固定使用某个供应商，而非自动路由。

SmsSignature { signature_id, text, type, review_state, reject_reason, vendor, created_at }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

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": "Acme", "type": "company"}'

sms.signature.get

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

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

参数

名称	类型	必填	说明
`id`	`string`	必填	签名 ID。

SmsSignature

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/sms/signature/get/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

sms.signature.list

GET /v1/sms/signature/list

分页列出短信签名。

参数

名称	类型	必填	说明
`cursor`	`string`	可选	分页游标，从上一页的 next_cursor 取得。
`limit`	`number`	可选	单页返回的最大条数。

SmsSignatureListResult { items, next_cursor }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/sms/signature/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

sms.signature.delete

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

删除一个短信签名。

参数

名称	类型	必填	说明
`id`	`string`	必填	要删除的签名 ID。
`idempotency_key`	`string`	可选	去重键；相同重试返回相同结果。

SmsDeleteResult { deleted }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X DELETE https://api.infrai.cc/v1/sms/signature/delete/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

sms.template.create

POST /v1/sms/template/create

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

参数

名称	类型	必填	说明
`name`	`string`	必填	模板名称。
`body`	`string`	必填	模板正文，可含｛变量｝占位符。
`locale`	`string`	可选	模板语言区域，如 en、zh。
`variables`	`string[]`	可选	模板中使用的变量名列表。
`vendor`	`string`	可选	固定使用某个供应商，而非自动路由。

SmsTemplate { template_id, name, body, locale, variables, review_state, created_at }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

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": "otp", "body": "Your code is {{code}}", "locale": "zh"}'

sms.template.get

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

读取单个短信模板。

参数

名称	类型	必填	说明
`id`	`string`	必填	模板 ID。

SmsTemplate

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/sms/template/get/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

sms.template.list

GET /v1/sms/template/list

分页列出短信模板。

参数

名称	类型	必填	说明
`cursor`	`string`	可选	分页游标，从上一页的 next_cursor 取得。
`limit`	`number`	可选	单页返回的最大条数。

SmsTemplateListResult { items, next_cursor }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/sms/template/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

sms.template.delete

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

删除一个短信模板。

参数

名称	类型	必填	说明
`id`	`string`	必填	要删除的模板 ID。
`idempotency_key`	`string`	可选	去重键；相同重试返回相同结果。

SmsDeleteResult { deleted }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X DELETE https://api.infrai.cc/v1/sms/template/delete/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

sms.suppress

POST /v1/sms/suppress

将号码加入抑制（免打扰）列表。

参数

名称	类型	必填	说明
`phone`	`string`	必填	要抑制的电话号码（E.164 格式）。
`reason`	`string`	可选	抑制原因，如 opt_out、complaint。
`scope`	`string`	可选	抑制范围，如 account、global。
`sender_scope`	`string`	可选	限定到某发送号的抑制范围。
`notes`	`string`	可选	内部备注说明。
`idempotency_key`	`string`	可选	去重键；相同重试返回相同结果。

SuppressionRecord { phone, scope, reason, created_at }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/sms/suppress \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "..."}'

sms.suppression.check

POST /v1/sms/suppression/check

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

参数

名称	类型	必填	说明
`phone`	`string`	必填	要检查的电话号码（E.164 格式）。
`scope`	`string`	可选	检查的抑制范围，如 account、global。
`sender_scope`	`string`	可选	限定到某发送号的检查范围。

SmsSuppressionCheckResult { suppressed, record }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

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": "..."}'

sms.suppression.list

GET /v1/sms/suppression/list

分页列出被抑制的号码。

参数

名称	类型	必填	说明
`cursor`	`string`	可选	分页游标，从上一页的 next_cursor 取得。
`limit`	`number`	可选	单页返回的最大条数。

SmsSuppressionListResult { items, total_count, next_cursor }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/sms/suppression/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

sms.suppression.delete

POST /v1/sms/suppression/delete

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

参数

名称	类型	必填	说明
`phone`	`string`	必填	要移除的电话号码（E.164 格式）。
`scope`	`string`	可选	移除的抑制范围，如 account、global。
`sender_scope`	`string`	可选	限定到某发送号的移除范围。
`idempotency_key`	`string`	可选	去重键；相同重试返回相同结果。

SmsSuppressionRemoveResult { phone, removed }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

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": "..."}'

sms.suppression.gdpr_remove

POST /v1/sms/suppression/gdpr_remove

GDPR 删除：凭确认令牌硬删除某号码的抑制数据。

参数

名称	类型	必填	说明
`phone`	`string`	必填	要执行 GDPR 删除的电话号码（E.164 格式）。
`confirmation_token`	`string`	必填	执行硬删除所需的确认令牌。
`idempotency_key`	`string`	可选	去重键；相同重试返回相同结果。

SmsSuppressionRemoveResult { phone, removed }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/sms/suppression/gdpr_remove \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "...", "confirmation_token": "..."}'

sms.usage

GET /v1/sms/usage

按时间窗聚合短信用量与成本统计。

参数

名称	类型	必填	说明
`since`	`string`	可选	统计起始时间（ISO 8601）。
`until`	`string`	可选	统计结束时间（ISO 8601）。
`vendor`	`string`	可选	固定使用某个供应商，而非自动路由。
`bucket`	`string`	可选	聚合粒度，如 day、hour。

SmsUsageResult { sent, delivered, failed, segments, cost_usd, delivery_rate, buckets }

示例

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/sms/usage \
  -H "Authorization: Bearer $INFRAI_API_KEY"

全部能力

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

能力	端点	说明
`sms.batch.send`	`POST /v1/sms/batch/send`	Send a heterogeneous batch of SMS (each a full request) under one idempotency key, billed per message.
`sms.cancel`	`POST /v1/sms/cancel/{id}`	Cancel a scheduled or queued SMS that has not yet been dispatched.
`sms.events`	`GET /v1/sms/events/{id}`	Retrieve the delivery event timeline for a single SMS message.
`sms.inbound.list`	`GET /v1/sms/inbound/list`	List inbound (reply) SMS received on registered sender numbers, with pagination.
`sms.list`	`GET /v1/sms/list`	List sent SMS message records with pagination.
`sms.lookup`	`POST /v1/sms/lookup`	Validate a phone number and enrich it with carrier and line-type information.
`sms.otp`	`POST /v1/sms/otp`	Send a one-time passcode via SMS with gateway-managed OTP lifecycle.
`sms.resend`	`POST /v1/sms/resend/{id}`	Resend an SMS, optionally retrying only the failed recipients.
`sms.send`	`POST /v1/sms/send`	Send an SMS message to one or more recipients (idempotent).
`sms.sender.delete`	`DELETE /v1/sms/sender/delete/{id}`	Delete a registered sender number.
`sms.sender.get`	`GET /v1/sms/sender/get/{id}`	Retrieve details of a single registered sender number.
`sms.sender.list`	`GET /v1/sms/sender/list`	List registered sender numbers with pagination.
`sms.sender.register`	`POST /v1/sms/sender/register`	Register a sender number for verification.
`sms.sender.reputation`	`GET /v1/sms/sender/reputation/{id}`	Query a sender number's reputation score and throttling risk.
`sms.sender.verify`	`POST /v1/sms/sender/verify`	Verify a registered sender number with a confirmation code.
`sms.signature.create`	`POST /v1/sms/signature/create`	Create an SMS signature (required for China delivery) and submit it for review.
`sms.signature.delete`	`DELETE /v1/sms/signature/delete/{id}`	Delete an SMS signature.
`sms.signature.get`	`GET /v1/sms/signature/get/{id}`	Retrieve a single SMS signature and its review status.
`sms.signature.list`	`GET /v1/sms/signature/list`	List SMS signatures with pagination.
`sms.status`	`GET /v1/sms/status/{id}`	Query the delivery status of an SMS message by ID.
`sms.suppress`	`POST /v1/sms/suppress`	Add a phone number to the suppression (do-not-contact) list.
`sms.suppression.check`	`POST /v1/sms/suppression/check`	Check whether a phone number is suppressed before sending.
`sms.suppression.delete`	`POST /v1/sms/suppression/delete`	Remove a number from the suppression list to resume sending.
`sms.suppression.gdpr_remove`	`POST /v1/sms/suppression/gdpr_remove`	Hard-delete a number's suppression record under GDPR, authorized by a confirmation token.
`sms.suppression.list`	`GET /v1/sms/suppression/list`	List suppressed phone numbers with pagination.
`sms.template.create`	`POST /v1/sms/template/create`	Create a reusable SMS template with named variables.
`sms.template.delete`	`DELETE /v1/sms/template/delete/{id}`	Delete an SMS template.
`sms.template.get`	`GET /v1/sms/template/get/{id}`	Retrieve a single SMS template.
`sms.template.list`	`GET /v1/sms/template/list`	List SMS templates with pagination.
`sms.usage`	`GET /v1/sms/usage`	Aggregate SMS usage and cost statistics over a time window.
`sms.verify`	`POST /v1/sms/verify`	Verify a user-submitted SMS one-time passcode.

完整示例

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

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

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

# 1) Auth: every call is a raw HTTPS request to the Infrai gateway carrying
#    only your project key. No SDK, no install.
#    Get your key: sign in with Google/GitHub at the console for a project key
#    + $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
#    POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."   # from the console


# 2) sms.send
curl -X POST https://api.infrai.cc/v1/sms/send \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+14155550100", "body": "Your code is 123456"}'

# 3) sms.otp
curl -X POST https://api.infrai.cc/v1/sms/otp \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "..."}'

# 4) sms.verify
curl -X POST https://api.infrai.cc/v1/sms/verify \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "...", "code": "..."}'

# 5) sms.status
curl -X GET https://api.infrai.cc/v1/sms/status/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

# 6) sms.batch.send
curl -X POST https://api.infrai.cc/v1/sms/batch/send \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages": []}'

# 7) sms.cancel
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": "..."}'

# 8) sms.events
curl -X GET https://api.infrai.cc/v1/sms/events/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

# 9) sms.inbound.list
curl -X GET https://api.infrai.cc/v1/sms/inbound/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"