API: internationalsms/MultiSend - 国际短信一对多发送


概览


internationalsms/multisend 是 SUBMAIL API 一对多(即1条API请求发送多个号码,可以灵活控制每个联系人的文本变量,并且无需提前创建模板)和群发 API 。(建议:单线程提交数量控制在50个联系人, 可以开多个线程同时发送)

使用方法与 sms/send 极为相似,不同的是 internationalsms/multisend 去除了 to 参数将其整合到 multi 参数中,并且 content 参数将支持使用 @var(key) 方式申明文本变量,multi 参数可以将联系人的手机号码,和不同的文本变量整合,实现一对多场景中灵活控制文本变量的功能。


开发者们可在提交 internationalsms/multisend API 时,将 tovars 参数编码为 JSON 字符串格式添加到 multi 参数中提交,multi 参数的数据模型请参考以下示例:

multi=[{
        "to":"886*********",
        "vars":{
            "name":"kevin",
            "code":123456
        }
    },{
        "to":"852*********",
        "vars":{
            "name":"jacky",
            "code":236554
        }
    },{
        "to":"13*********",
        "vars":{
            "name":"tom",
            "code":236554
        }]


完整的 internationalsms/multisend POST 请求请参考以下示例:

appid=your_app_id
content=[SUBMAIL]您好,@var(name),您的取货码为 @var(code)
multi=[{
    "to":"886*********",
    "vars":{
        "name":"kevin",
        "code":123456
    }
},{
    "to":"852*********",
    "vars":{
        "name":"jacky",
        "code":236554
    }
},{
    "to":"13*********",
    "vars":{
        "name":"tom",
        "code":236554
    }]
signature=your_app_key


URL


https://api-v4.mysubmail.com/internationalsms/multisend


支持格式


格式URL
jsonhttps://api-v4.mysubmail.com/internationalsms/multisend.json (默认)
xmlhttps://api-v4.mysubmail.com/internationalsms/multisend.xml
yamlhttps://api-v4.mysubmail.com/internationalsms/multisend.yaml


http 请求方式


请求方式content-type设置
http postmultipart/form-datax-www-form-urlencodedapplication/json


是否需要授权


参阅 API 授权和验证机制


请求参数


参数类型必需/可选默认描述
appidstring必需在 SUBMAIL -国际短信-创建/管理appid菜单中创建
contentstring必需短信正文。
multijson string必需收件人 to 联系人参数和 vars 文本变量的整合模式,请将 to 和 vars 整合成 json字符串格式提交(数据模型请参考本页概览处multi参数示例)
tagstring可选自定义标签功能,该标签可用作SUBHOOK追踪
(32 个字符以内,添加了 tag 参数的 API 请求,会在所有的 SUBHOOK 事件中携带此参数。tag参数不参加加密计算)
timestampUNIX 时间戳可选参阅 API 授权与验证机制 > Timestamp UNIX 时间戳
sign_typestring可选normalAPI 授权模式( md5 or sha1 or normal
参阅 API 授权与验证机制 > 授权和验证方式
sign_versionstring可选2signature加密计算方式(当sign_version传2时,multi,content参数不参与加密计算)
signaturestring必需appkey或数字签名
参阅 API授权与验证机制 > 授权和验证方式


注意:
multi 参数要求严格的 JSON 格式,以下是将参数转换为 JSON 格式的注意事项

json 字符串必须以双引号包含
json 字符串必须是 utf8 编码
不能有多余的逗号 如:[1,2,]
 json 字符串首尾必须被大括号{}包含 
 
PS:大多数的语言都有专属的JSON解析器( ENCODING 和 DECODEING 方法)。如 PHP,首先将需要的变量以数组形式(如 $var[‘key’]=value) 创建后,使用 json_encode($var)方法创建 JSON 字符串;


代码示例


发送一封测试短信


POST URL
https://api-v4.mysubmail.com/internationalsms/multisend


POST DATA
appid=your_app_id
&content=[SUBMAIL]您好,@var(name),您的取货码为 @var(code)
&multi=[{
    "to":"886*********",
    "vars":{
        "name":"kevin",
        "code":123456
        }
    },{
    "to":"852*********",
    "vars":{
        "name":"jacky",
        "code":236554
        }
    }]
&signature=your_app_key




返回值


请求成功
[
  {
    "status": "success",
    'to': '+15xxxxxxxxx',
    "send_id": ""c2f0e679ad8dc2bf6cb71bf2925665e0",
    "fee": "0.1"
    },{
    "status": "success",
    'to': '+15xxxxxxxxx',
    "send_id": ""c2f0e679ad8dc2bf6cb71bf2925665e0",
    "fee": "0.1"
    }
]


请求失败
[
   {
        "status":"error",
        "code":1xx,
        "msg":"error sms"
    },{
    "status": "success",
    'to': '+15xxxxxxxxx',
    "send_id": ""c2f0e679ad8dc2bf6cb71bf2925665e0",
    "fee": "0.1"
    }
]

注:internationalsms/multisend API 中返回码将包含成功和失败的状态 ,API 在一条API中发起对多个号码的请求,所以返回状态也是按多条API计算的,例如:单次请求中包含3个联系人,其中2个联系人请求成功,1个联系人请求失败时,此时的API返回状态,将包含3条状态数组(即2条 status:success ,1条 status:error 的状态)



错误代码


参阅 [API 错误代码]