API: Message/multixsend
概览
message/multixsend
是 SUBMAIL 的短信一对多(即1条API请求发送多个号码,并可以灵活控制每个联系人的文本变量)和群发 API 。(建议: 单线程提交数量控制在50—200个联系人, 可以开多个线程同时发送)
与 message/xsend
API 一样,message/multixsend
提供完整且强大的短信发送功能,message/multixsend
解决开发者在应用场景中的一对多或群发的需求,极大的提高 API 并发效率。
使用方法与 message/xsend
极为相似,不同的是 message/multixsend
去除了 to
和 vars
参数将其整合到 multi
参数中,可以将联系人的手机号码,和不同的文本变量整合,实现一对多场景中灵活控制文本变量的功能。
开发者们可在提交 message/multixsend
API 时,将 to
和 vars
参数编码为 JSON
字符串格式添加到 multi
参数中提交,multi
参数的数据模型请参考以下示例:
multi=[{
"to":"15*********",
"vars":{
"name":"kevin",
"code":123456
}
},{
"to":"18*********",
"vars":{
"name":"jacky",
"code":236554
}
},{
"to":"13*********",
"vars":{
"name":"tom",
"code":236554
}]
完整的 message/multixsend
POST 请求请参考以下示例:
appid=your_app_id
project=EM9sd
multi=[{
"to":"15*********",
"vars":{
"name":"kevin",
"code":123456
}
},{
"to":"18*********",
"vars":{
"name":"jacky",
"code":236554
}
},{
"to":"13*********",
"vars":{
"name":"tom",
"code":236554
}]
signature=your_app_key
URL
<主> https://api.mysubmail.com/message/multixsend
<备> https://api.submail.cn/message/multixsend
支持格式
格式 | URL |
---|---|
json | https://api.mysubmail.com/message/multixsend.json (默认) |
xml | https://api.mysubmail.com/message/multixsend.xml |
http 请求方式
请求方式 | content-type设置 |
---|---|
http post | multipart/form-data 、x-www-form-urlencoded 、application/json |
是否需要授权
是
参阅 API 授权和验证机制
请求参数
参数 | 类型 | 必需/可选 | 默认 | 描述 |
---|---|---|---|---|
appid | string | 必需 | 无 | 在 SUBMAIL 应用集成中创建的短信应用ID |
project | string | 必需 | 无 | 项目标记 (ID) 在 SUBMAIL > Message >项目中查看你所创建的短信项目标记。请参见获取项目或地址薄的开发者标识 |
multi | json string | 必需 | 无 | 收件人 to 联系人参数和 vars 文本变量的整合模式,请将 to 和 vars 整合成 json字符串格式提交(数据模型请参考本页概览处multi参数示例) |
tag | string | 可选 | 无 | 自定义标签功能,该标签可用作SUBHOOK追踪(32 个字符以内)tag参数不参加加密计算 |
timestamp | UNIX 时间戳 | 可选 | 无 | 参阅 API 授权与验证机制 > Timestamp UNIX 时间戳 |
sign_type | string | 可选 | normal | API 授权模式( md5 or sha1 or normal )参阅 API 授权与验证机制 > 授权和验证方式 |
sign_version | string | 可选 | 无 | signature加密计算方式(当sign_version传2时,multi,content参数不参与加密计算) |
signature | string | 必需 | 无 | 应用密匙或数字签名 参阅 API授权与验证机制 > 授权和验证方式 |
代码示例
发送一封测试短信
POST URL
https://api.mysubmail.com/message/multixsend.json
POST DATA
appid=your_app_id
&project=ThJBE4
&multi=[{
"to":"15*********",
"vars":{
"name":"kevin",
"code":123456
}
},{
"to":"18*********",
"vars":{
"name":"jacky",
"code":236554
}
}]
&signature=your_app_key
返回
[
{
"status":"success",
"to":"15*********",
"send_id":"093c0a7df143c087d6cba9cdf0cf3738",
"fee":1,
"sms_credits": "21128",
"transactional_sms_credits": "0"
},{
"status":"success",
"to":"18*********",
"send_id":"093c0a7df143c087d6cba9cdf0cf3738",
"fee":1,
"sms_credits": "21127",
"transactional_sms_credits": "0"
}
]
返回值
请求成功
[
{
"status":"success",
"to":"15*********",
"send_id":"093c0a7df143c087d6cba9cdf0cf3738",
"fee":1,
"sms_credits": "21128",
"transactional_sms_credits": "0"
},{
"status":"success",
"to":"18*********",
"send_id":"093c0a7df143c087d6cba9cdf0cf3738",
"fee":1,
"sms_credits": "21127",
"transactional_sms_credits": "0"
}
]
请求失败
[
{
"status":"error",
"to":"15*********",
"code":1xx,
"msg":"error message",
},{
"status":"success",
"to":"18*********",
"send_id":"093c0a7df143c087d6cba9cdf0cf3738",
"sms_credits": "21128",
"transactional_sms_credits": "0"
}
]
- 注:
message/multixsend API
中返回码将包含成功和失败的状态 ,API 在一条API中发起对多个号码的请求,所以返回状态也是按多条API计算的,例如:单次请求中包含3个联系人,其中2个联系人请求成功,1个联系人请求失败时,此时的API返回状态,将包含3条状态数组(即2条status:success
,1条status:error
的状态)