短信 API：快速接入消息发送文档

1. 准备鉴权

在服务端调用，设置 api-key 和 Content-Type: application/json 请求头。

2. 理解 params 与占位符

模板中的 ${code} 是占位符。发送时，params.code 提供本次要替换的值：

模板 · 预留动态内容

text

您的验证码为${code}，5分钟内有效。

参数 · 填入本次值

json

{ "params": { "code": "008848" } }

收件人看到的短信

您的验证码为008848，5分钟内有效。

key 写 code，不写 ${code}，并与占位符大小写一致。值使用纯数字字符串，如 "008848"；无占位符时可省略 params。

3. 调用发送接口

POSThttps://api.starsg.ai/api/product/sms/send

字段	类型	必填	填写说明
templateId	string	是	审核通过的模板 ID，例如 SMS_0123456789；保留大小写。
countryCode	string	是	国家或地区拨号码，例如法国填写 "33"；不带 +，与 phone 分开填写，支持范围见下方国家列表。
phone	string	是	接收短信的手机号，不含国家码。
params	object<string, string>	按模板	占位符名称到实际值的映射，例如 {"code":"008848"}；默认只接受纯数字字符串。无占位符时可省略。

复制并修改这个示例

示例使用法国拨号码 33。执行前请替换 API Key、已审核的模板 ID 和你自己的测试号码，并确认目的地已开放。

bash

curl -X POST 'https://api.starsg.ai/api/product/sms/send' \
  -H 'api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "templateId": "SMS_0123456789",
    "countryCode": "33",
    "phone": "612345678",
    "params": { "code": "008848" }
  }'

直接发送 JSON 对象，不包 body、不加 /v1。此示例适用于含 ${code} 的模板。

4. 查看调用结果

先判断 success。成功时保存 messageId（渠道消息 ID）和 resultId（发送流水号）；失败时查看 errorCode/errorMsg。发送成功不代表手机已收到。

成功响应

json

{
  "success": true,
  "data": {
    "messageId": "channel-message-id",
    "resultId": 9
  },
  "errorCode": null,
  "errorMsg": null
}

失败响应

json

{
  "success": false,
  "data": null,
  "errorCode": "END_USER_TEMPLATE_NOT_APPROVED",
  "errorMsg": "Template is awaiting review"
}

常见错误与处理

`001`	检查必填字段、JSON 格式、手机号国家码及 params 是否为纯数字字符串。
`END_USER_TEMPLATE_NOT_FOUND`	确认模板 ID 完整且属于当前 API Key 对应用户。
`END_USER_TEMPLATE_NOT_APPROVED`	模板审核中；审核通过后再发送。
`END_USER_TEMPLATE_REJECTED`	模板未通过；查看拒绝原因，修改后重新申请。
`USER_SEND_TOO_MUCH / USER_REG_PHONE_SEND_TOO_MUCH`	触发频控，降低调用频率。
`ENV_LIMITER / TEMPLATE_LIMITER`	命中环境或模板策略限制，按错误提示联系支持。
`SEND_FAIL / SMS_SEND_FAIL / END_USER_SEND_FAILED / 999`	记录错误和请求标识，联系支持排查，不要盲目重复发送。
`METERING_MISSING`	短信可能已经发出，但计量数据缺失。不要自动重发，保留 resultId 并联系支持核对。

支持国家与地区

发送前请确认目的地的开放状态。需要注册 SID 的国家或地区即将开放；countryCode 请填写下表中的拨号码，不带 +，并将手机号码单独填写在 phone 中。

查找国家或地区

国家 / 地区	拨号码	开放状态
美国	+1	即将开放
俄罗斯	+7	即将开放
埃及	+20	即将开放
南非	+27	已开放
希腊	+30	已开放
荷兰	+31	已开放
比利时	+32	已开放
法国	+33	已开放
西班牙	+34	已开放
匈牙利	+36	已开放
意大利	+39	已开放
罗马尼亚	+40	已开放
瑞士	+41	已开放
奥地利	+43	已开放
英国	+44	即将开放
丹麦	+45	已开放
挪威	+47	已开放
瑞典	+46	已开放
波兰	+48	已开放
德国	+49	已开放
秘鲁	+51	已开放
墨西哥	+52	已开放
阿根廷	+54	已开放
巴西	+55	已开放
智利	+56	已开放
哥伦比亚	+57	已开放
委内瑞拉	+58	已开放
马来西亚	+60	已开放
澳大利亚	+61	即将开放
印度尼西亚	+62	即将开放
菲律宾	+63	即将开放
新西兰	+64	已开放
新加坡	+65	即将开放
泰国	+66	即将开放
日本	+81	已开放
韩国	+82	已开放
越南	+84	即将开放
中国	+86	即将开放
土耳其	+90	即将开放
印度	+91	已开放
巴基斯坦	+92	即将开放
阿富汗	+93	即将开放
斯里兰卡	+94	即将开放
缅甸	+95	即将开放
南苏丹	+211	已开放
摩洛哥	+212	即将开放
阿尔及利亚	+213	已开放
突尼斯	+216	已开放
利比亚	+218	即将开放
冈比亚	+220	已开放
塞内加尔	+221	已开放
毛里塔尼亚	+222	即将开放
马里	+223	即将开放
几内亚	+224	即将开放
科特迪瓦	+225	已开放
布基纳法索	+226	已开放
尼日尔	+227	已开放
多哥	+228	已开放
贝宁	+229	即将开放
毛里求斯	+230	即将开放
利比里亚	+231	即将开放
塞拉利昂	+232	即将开放
加纳	+233	即将开放
尼日利亚	+234	即将开放
乍得	+235	即将开放
中非	+236	已开放
喀麦隆	+237	即将开放
佛得角	+238	已开放
圣多美和普林西比	+239	已开放
赤道几内亚	+240	已开放
加蓬	+241	已开放
刚果（布）	+242	已开放
刚果（金）	+243	已开放
安哥拉	+244	已开放
几内亚比绍	+245	即将开放
英属印度洋领土	+246	已开放
阿森松岛	+247	已开放
塞舌尔	+248	已开放
苏丹	+249	即将开放
卢旺达	+250	即将开放
埃塞俄比亚	+251	即将开放
索马里	+252	已开放
吉布提	+253	已开放
肯尼亚	+254	即将开放
坦桑尼亚	+255	即将开放
乌干达	+256	即将开放
布隆迪	+257	已开放
莫桑比克	+258	已开放
赞比亚	+260	即将开放
马达加斯加	+261	已开放
留尼汪	+262	已开放
津巴布韦	+263	已开放
纳米比亚	+264	已开放
马拉维	+265	即将开放
莱索托	+266	已开放
博茨瓦纳	+267	已开放
斯威士兰	+268	已开放
科摩罗	+269	已开放
圣赫勒拿	+290	已开放
厄立特里亚	+291	已开放
阿鲁巴	+297	已开放
法罗群岛	+298	已开放
格陵兰	+299	已开放
直布罗陀	+350	已开放
葡萄牙	+351	已开放
卢森堡	+352	已开放
爱尔兰	+353	已开放
冰岛	+354	已开放
阿尔巴尼亚	+355	已开放
马耳他	+356	已开放
塞浦路斯	+357	已开放
芬兰	+358	已开放
保加利亚	+359	已开放
立陶宛	+370	已开放
拉脱维亚	+371	已开放
爱沙尼亚	+372	已开放
摩尔多瓦	+373	已开放
亚美尼亚	+374	即将开放
白俄罗斯	+375	即将开放
安道尔	+376	已开放
摩纳哥	+377	已开放
圣马力诺	+378	已开放
乌克兰	+380	已开放
塞尔维亚	+381	已开放
黑山	+382	已开放
科索沃	+383	已开放
克罗地亚	+385	已开放
斯洛文尼亚	+386	已开放
波斯尼亚和黑塞哥维那	+387	已开放
北马其顿	+389	已开放
捷克	+420	即将开放
斯洛伐克	+421	已开放
列支敦士登	+423	已开放
福克兰群岛	+500	已开放
伯利兹	+501	已开放
危地马拉	+502	已开放
萨尔瓦多	+503	已开放
洪都拉斯	+504	已开放
尼加拉瓜	+505	已开放
哥斯达黎加	+506	已开放
巴拿马	+507	已开放
圣皮埃尔和密克隆	+508	已开放
海地	+509	已开放
瓜德罗普	+590	已开放
玻利维亚	+591	已开放
圭亚那	+592	已开放
厄瓜多尔	+593	已开放
法属圭亚那	+594	已开放
巴拉圭	+595	已开放
马提尼克	+596	已开放
苏里南	+597	已开放
乌拉圭	+598	已开放
荷属加勒比（库拉索等）	+599	已开放
东帝汶	+670	已开放
诺福克岛	+672	已开放
文莱	+673	已开放
瑙鲁	+674	已开放
巴布亚新几内亚	+675	已开放
汤加	+676	已开放
所罗门群岛	+677	已开放
瓦努阿图	+678	已开放
斐济	+679	已开放
帕劳	+680	已开放
瓦利斯和富图纳	+681	已开放
库克群岛	+682	已开放
纽埃岛	+683	已开放
萨摩亚	+685	已开放
基里巴斯	+686	已开放
新喀里多尼亚	+687	已开放
图瓦卢	+688	已开放
法属波利尼西亚	+689	已开放
托克劳	+690	已开放
密克罗尼西亚	+691	已开放
马绍尔群岛	+692	已开放
中国香港	+852	即将开放
中国澳门	+853	已开放
柬埔寨	+855	即将开放
老挝	+856	已开放
孟加拉国	+880	已开放
中国台湾	+886	已开放
马尔代夫	+960	已开放
黎巴嫩	+961	已开放
约旦	+962	即将开放
伊拉克	+964	已开放
科威特	+965	即将开放
沙特阿拉伯	+966	即将开放
也门	+967	即将开放
阿曼	+968	即将开放
巴勒斯坦	+970	即将开放
阿联酋	+971	即将开放
以色列	+972	已开放
巴林	+973	已开放
卡塔尔	+974	即将开放
不丹	+975	已开放
蒙古国	+976	已开放
尼泊尔	+977	即将开放
塔吉克斯坦	+992	已开放
土库曼斯坦	+993	已开放
阿塞拜疆	+994	已开放
格鲁吉亚	+995	已开放
吉尔吉斯斯坦	+996	已开放
乌兹别克斯坦	+998	已开放
巴哈马	+1242	已开放
巴巴多斯	+1246	已开放
安圭拉	+1264	已开放
安提瓜和巴布达	+1268	已开放
英属维尔京群岛	+1284	已开放
美属维尔京群岛	+1340	已开放
开曼群岛	+1345	已开放
百慕大	+1441	已开放
格林纳达	+1473	已开放
特克斯和凯科斯群岛	+1649	已开放
蒙特塞拉特	+1664	已开放
北马里亚纳群岛	+1670	已开放
关岛	+1671	已开放
美属萨摩亚	+1684	已开放
圣马丁	+1721	已开放
圣卢西亚	+1758	已开放
多米尼克	+1767	已开放
波多黎各	+1787	已开放
多米尼加	+1809	已开放
特立尼达和多巴哥	+1868	已开放
圣基茨和尼维斯	+1869	已开放
牙买加	+1876	已开放