发送相关

send

发送一个短信模板给一个或多个用户

URL

https://api.sendcloud.net/smsapi/send

返回数据格式

json

HTTP请求方式 

POST

参数说明

参数 类型 必选 说明
smsUser string 是 smsUser
templateId int 是 模板ID
labelId int 否 短信标签ID
msgType int 否 0表示短信, 1表示彩信,2表示国际短信,3表示国内语音,5表示影音 默认值为0
phone string 是 收信人手机号,多个手机号用逗号,分隔，每次调用最大支持2000，更多地址建议使用联系人列表功能
vars string 否 替换变量的json串
sendRequestId string 否 最大支持128字符,1小时内相同sendRequestId的多次请求只会处理第一次
signature string 是 数字签名, 合法性验证，详情见API 验证机制
timestamp string 否 UNIX时间戳
tag string 否 值为json 格式字符串,最大字符长度为128,比如:{"key1": "value1", "key2": "value2"}

vars格式示例:

{"name": "lucy"} or {"%money%": "100"}

注意:

  1. 系统会用vars中的参数替换短信模板中的变量, 所有手机号收到替换后的同一个内容. 参数 vars 可能含有特殊字符, 记得 urlencode.

  2. vars 所传递的变量的值, 长度默认不能超过16个字符, 格式为字符串, 变量中不能含有 HTTP 链接（特殊需求请联系客服）

  3. 生成签名时, 参数不要使用 urlencode. 在调用 api 时, 才需要对参数做 urlencode

  4. msgType为5，表示可发送同时包含文字、图片、音频、视频信息的视频短信，也叫影信，可达2MB大小，详情见视频短信

sendVoice

发送语音验证码

URL

https://api.sendcloud.net/smsapi/sendVoice

返回数据格式

json

HTTP请求方式

POST

参数说明

参数 类型 必选 说明
smsUser string 是 smsUser
phone string 是 收信人手机号
code string 是 验证码
labelId int 否 短信标签ID
sendRequestId string 否 最大支持128字符,1小时内相同sendRequestId的多次请求只会处理第一次
signature string 是 数字签名, 合法性验证
timestamp string 否 UNIX时间戳
tag string 否 值为json 格式字符串,最大字符长度为128,比如:{"key1": "value1", "key2": "value2"}

code格式示例:

{"code": "123456"}

注意:

  1. 参数 code 格式为字符串,内容为4-6位长度的数字
  2. 此接口不支持国际短信

sendCode（不需要短信模板）

发送短信验证码

URL

https://api.sendcloud.net/smsapi/sendCode

返回数据格式

json

HTTP请求方式

POST

参数说明

参数 类型 必选 说明
smsUser string 是 smsUser
msgType int 是 0表示短信,2表示国际短信,默认值为0
phone string 是 收信人手机号
signId Integer * 短信签名id
signName string * 短信签名名称
code string 是 验证码
labelId int 否 短信标签ID
sendRequestId string 否 最大支持128字符,1小时内相同sendRequestId的多次请求只会处理第一次
signature string 是 数字签名, 合法性验证
timestamp string 否 UNIX时间戳
tag string 否 值为json 格式字符串,最大字符长度为128,比如:{"key1": "value1", "key2": "value2"}

code格式示例:

{"code": "123456"}

注意:

  1. 参数 code 格式为字符串,内容为4-6位长度的数字
  2. signId为短信签名的id，signId和signName两个参数只需要传一个即可，如果signId不为空，signName自动忽略

timestamp

获取服务器时间戳

URL

https://api.sendcloud.net/smsapi/timestamp/get

返回数据格式

json

HTTP请求方式 

GET

参数说明

无

返回码

短信 API 返回的结果是 JSON 格式, 示例如下: 

# 请求成功
{
    "message":"请求成功",
    "info":{"successCount":1,"smsIds":["1458113381893_15_3_11_1ainnq$131112345678"]}},
    "result":true,
    "statusCode":200
}

# 手机号格式错误
{
    "message":"手机号格式错误",
    "info":{},
    "result":false,
    "statusCode":412
}

# 部分成功
{
    "message":"部分成功",
    "info":{
            "successCount":1,
            "failedCount":1,
            "items":[{"phone":"1312222","vars":{},"message":"手机号格式错误"}],
            "smsIds":["1458113381893_15_3_11_1ainnq$131112345678"]}
            },
    "result":true,
    "statusCode":311
}
API 返回码 含义
200 请求成功
311 部分号码请求成功
312 全部请求失败
400 重复请求
401 短信内容不能为空
402 短信内容不能超过%s个字符
403 此接口暂不支持此类 msgType
411 手机号不能为空
412 手机号格式错误
413 有重复的手机号
414 有重复的手机号
415 手机号检测个数不能超过%s个,且不能为0个
416 tag格式错误
417 tag长度不能超过128个字符
421 数字签名参数错误
422 数字签名错误
431 模板不存在
432 模板未提交审核或者未审核通过
433 模版ID不能为空
434 模板类型不匹配
435 模板名称不能为空
436 模板名称不能超过64个字节
437 模板内容不能为空
438 模板内容不超过512个字节
439 彩信标题不超过50个字节
440 【】表示短信签名，模板内容或彩信标题不能包含
441 替换变量格式错误
451 定时发送时间的格式错误
452 定时发送时间早于服务器时间, 时间已过去
461 时间戳无效, 与服务器时间间隔大于6秒
471 smsUser不存在
472 smsUser不能为空
473 没有权限, 免费用户不能发送短信
474 用户不存在
481 手机号和替换变量不能为空
482 手机号和替换变量格式错误
483 替换变量长度不能超过16或32个字符
499 账户额度不够
501 服务器异常
601 你没有权限访问 说明：IP防护的拦截
602 您没有使用该接口的权限 说明：没有调用sendVoice的权限
7241 phones列表成员号码最多不能超过100个
50000 接口频率受限(每个smsUser,每个接口、每分钟调用4000次，目前只限制投递回应)
SMSHook 错误码(statusCode) 含义
410 处理失败, 手机号在全局拦截列表
420 处理失败, 手机号在局部拦截列表
430 处理失败, 取消订阅
440 处理失败, 关键词过滤
450 处理失败, 替换变量错误
460 处理失败, 短信内容不能超过500个字符
500 发送失败, 手机空号
510 发送失败, 手机停机
550 发送失败, 该模板内容被投诉
580 发送失败, 手机关机
590 发送失败, 其他原因