发送相关
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"}
注意:
-
系统会用vars中的参数替换短信模板中的变量, 所有手机号收到替换后的同一个内容. 如果每个手机号传递变量内容不同时，需要多次调用接口. 参数 vars 可能含有特殊字符, 记得
urlencode. -
vars 所传递的变量的值, 长度默认不能超过16个字符, 格式为字符串, 变量中不能含有 HTTP 链接（特殊需求请联系客服）
-
生成签名时, 参数不要使用
urlencode. 在调用 api 时, 才需要对参数做urlencode -
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"}
注意:
- 参数 code 格式为字符串,内容为4-6位长度的数字
- 此接口不支持国际短信
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"}
注意:
- 参数 code 格式为字符串,内容为4-6位长度的数字
- 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
}
- result: API 请求是否成功
- statusCode: API 返回码
- message: API 返回码的中文解释
- info: 更多信息, 比如: 部分成功则返回具体失败信息, 获取时间戳则返回时间戳的值
| API 返回码 | 含义 |
|---|---|
| 200 | 请求成功 |
| 311 | 部分成功 |
| 312 | 全部失败 |
| 400 | 重复请求 |
| 401 | 短信内容不能为空 |
| 402 | 短信内容不能超过500个字符 |
| 403 | 此接口暂不支持此类 msgType |
| 404 | requestId不能超过128位 |
| 405 | requestId不能为空 |
| 411 | 手机号不能为空 |
| 412 | 手机号格式错误 |
| 413 | 有重复的手机号码 |
| 414 | 手机号个数不能超过2000个 |
| 415 | 手机号检测个数不能超过100个,且不能为0个 |
| 416 | tag格式错误 |
| 417 | tag长度不能超过128个字符 |
| 421 | 签名参数错误 |
| 422 | 签名错误 |
| 431 | 模版不存在 |
| 432 | 模板未提交审核或者未审核通过 |
| 433 | 模版ID不能为空 |
| 434 | 模板类型不匹配 |
| 435 | 模板名称不能为空 |
| 436 | 模板名称不能超过64个字节 |
| 437 | 模板内容不能为空 |
| 438 | 模板内容不超过512个字节 |
| 439 | 彩信标题不超过50个字节 |
| 440 | 模板内容或彩信标题不能包含【】、测试、test字符。 |
| 441 | 替换变量格式错误,变量名只能包含字母、数字、'_' |
| 442 | 验证码参数不能为空 |
| 443 | 验证码参数格式错误 |
| 451 | 定时开始时间格式错误 |
| 452 | 定时开始时间早于服务器时间，时间已过期 |
| 461 | 时间戳无效，与服务器时间超过6000毫秒 |
| 471 | smsUser不存在 |
| 472 | smsUser不能为空 |
| 4721 | smsKey不能为空 |
| 4722 | smsUser与smsKey不匹配 |
| 4723 | cmpp类型smsUser不能访问HTTP接口 |
| 473 | 没有权限,免费用户不能发送短信 |
| 474 | 用户不存在 |
| 481 | 手机号和替换变量不能为空 |
| 482 | 手机号和替换变量格式错误 |
| 483 | 替换变量长度不能超过16或32个字符 |
| 484 | 替换变量中不允许包含链接地址 |
| 485 | 手机号个数不能超过200个 |
| 491 | 扩展字段ext格式错误 |
| 496 | 一分钟内给当前地址发信太多 |
| 497 | 五分钟内给当前地址发信太多 |
| 498 | 一天内给当前地址发信太多 |
| 499 | 您的额度不够了 |
| 501 | 服务器异常 |
| 502 | 调用额度服务异常，请检查请求参数 |
| 510 | userId不能为空 |
| 601 | IP访问受限,请检查IP防护(白名单)设置 |
| 602 | 您没有使用该接口的权限 |
| 4340 | 彩信模板对应的内容不存在 |
| 4393 | 最多只能查询200条记录 |
| 43910 | 模板签名内容不能为空 |
| 43911 | signPositon不能为空 |
| 43912 | signPositon格式不符合规范 |
| 43913 | isVerify不能为空 |
| 43914 | isVerify格式不符合规范 |
| 43915 | signId不能为空 |
| 43916 | signId格式不符合规范 |
| 43917 | 未通过 企业认证，短信模版暂不可提交审核 |
| 43918 | 模板ID格式不正确 |
| 43919 | 模板名称重复 |
| 43920 | 模板签名只可包含纯中文、中英文混合、中数字混合、中英文数字混合，2~12个字符 |
| 43921 | 模板签名不存在 |
| 43922 | 彩信内容不能为空 |
| 43923 | 彩信内容最大只支持50kb |
| 43924 | 彩信内容不能为空 |
| 43925 | 彩信附件格式不符合规范 |
| 43926 | 彩信音频格式不符合规范 |
| 43927 | 彩信不能超过3页 |
| 43928 | 彩信每页最多只能包括文本、图片、音频各一个 |
| 43929 | msgType不匹配 |
| 43930 | msgType不能为空 |
| 43931 | 待审核的模板不能编辑 |
| 43932 | 尚未通过短信备案，短信模版暂不可创建 |
| 43940 | msgType格式不符合规范 |
| 43950 | mmsType不能为空 |
| 43960 | mmsType格式不符合规范 |
| 43970 | smsType不能为空 |
| 43980 | smsType格式不符合规范 |
| 7001 | days或者(startDate和endDate)不能为空 |
| 7002 | days格式非法,必须是[1,100]区间内的正整数（状态/退信查询类接口为[1,30]） |
| 7003 | startDate格式错误,应该类似'2013-03-19' |
| 7004 | endDate格式错误,应该类似'2013-03-19' |
| 7005 | startDate, endDate相隔不能超过100天 |
| 70051 | startDate, endDate相隔不能超过30天 |
| 7006 | templateIdsStr参数不能为空 |
| 7007 | templateIdsStr参数格式不正确 |
| 7008 | msgTypeStr不能为空 |
| 7009 | msgTypeStr参数格式错误 |
| 7010 | Aggregate参数格式错误 |
| 7011 | start参数格式错误 |
| 7012 | limit参数格式错误 |
| 7101 | labelId不能为空 |
| 7102 | labelId不属于此用户 |
| 7103 | labelId不存在 |
| 7104 | labelName格式不能超过255个字节 |
| 7105 | labelName不能为空 |
| 7106 | label类型不正确 |
| 7107 | label not exceed 110000 |
| 7108 | label not exceed 500000 |
| 7200 | 国际短信签名内容不能为纯数字 |
| 7201 | contactListName不能为空 |
| 7202 | contactListName已经存在 |
| 7203 | contactListName格式错误,只能是英文字母和数字,且不超过24个字符 |
| 7204 | description长度不能超过100个字节 |
| 7205 | contactListName不存在 |
| 7206 | phone不能为空 |
| 7207 | phone格式不正确 |
| 7208 | vars不能为空 |
| 7209 | vars格式不正确 |
| 7210 | 没有找到对应记录 |
| 7211 | taskName不能为空 |
| 7212 | taskName长度不能超过48个字节 |
| 7213 | senderName不能为空 |
| 7214 | senderName长度不能超过48个字节 |
| 7215 | taskId不能为空 |
| 7216 | newContactListName不能为空 |
| 7217 | contactListName格式错误,只能是英文字母和数字,且不超过24个字符 |
| 7218 | newContactListName已经存在 |
| 7219 | userName长度不能超过48个字节 |
| 7220 | executeTime格式不正确 |
| 7221 | signName不能为空 |
| 7222 | signName格式不正确,签名名称只可包含纯中文或中英文混合或纯英文或英文数字混合或中文和数字,且只能是2-12个字符 |
| 7223 | signType格式不正确,只能是0和1两种状态 |
| 7224 | signName已经存在 |
| 7225 | 最多只能创建10个短信签名 |
| 7226 | 短信签名id不能为空 |
| 7227 | 没有找到对应的短信签名 |
| 7228 | 该短信签名状态不允许修改 |
| 7229 | 短信签名signId和signName不能同时为空 |
| 7230 | 短信的签名与模板类型不匹配 |
| 7231 | qrcode不符合json规范 |
| 7232 | qrcode里面的content不能为空 |
| 7233 | qrcode里面的content不能超过10KB |
| 7234 | qrcode里面的content格式不正确 |
| 7235 | qrcode里面的type不能为空 |
| 7236 | qrcode里面的type格式错误 |
| 7237 | qrcode生成二维码错误 |
| 7238 | 发送二维码时候彩信第一页图片类型格式不对 |
| 7239 | 发送二维码时候彩信内容超过50KB |
| 7240 | contactListName不能超过5个 |
| 7241 | phones列表成员号码最多不能超过100个 |
| 7242 | phones列表中没有有效的成员号码 或者 与phones列表对应的userName(若有值)和vars(若有值)不符合格式或长度限制 |
| 7243 | phones列表的数据个数与userNames列表的数据个数不相等 |
| 7244 | phones列表的数据个数与vars列表的数据个数不相等 |
| 7245 | 参数sendToSubscriber值必须是0或者1 |
| 7246 | 参数estimateSendNum值必须是数字 |
| 7247 | 参数sendContentExample最大不能超过512个字符 |
| 7248 | 没有上传营业执照或者格式不对 |
| 7249 | 上传文件失败 |
| 7250 | 有短信模板正在使用该签名,无法删除签名 |
| 7251 | 仅可修改审核不通过的短信签名 |
| 7252 | isThirdRights格式不正确或者为空,值范围只能是0和1两种状态 |
| 7253 | signSource不正确 |
| 7254 | supplement长度应为0-256 |
| 7255 | 文件大小不得超过2MB |
| 7256 | 签名已经存在 |
| 7257 | 短信未备案，请登录网站提交短信备案 |
| 7258 | 签名与模板类型不匹配 |
| 7259 | 签名审核未通过 |
| 7260 | 回复状态 |
| 7261 | 回复状态值只能为true或false |
| 7262 | 回复时间不能为空 |
| 7263 | 回复时间只能是long类型 |
| 7264 | 短信ID不能为空 |
| 7265 | 第三方法人姓名不能为空 |
| 7266 | 第三方公司名称不能为空 |
| 7267 | 第三方公司统一社会信用代码不能为空 |
| 7268 | 第三方经办人姓名不能为空 |
| 7269 | 第三方经办人身份证号码不能为空 |
| 7270 | 第三方经办人手机号码不能为空 |
| 7271 | 附加图片需上传商标证书 |
| 101 | 保存失败 |
| 102 | 更新失败 |
| 103 | 删除失败 |
| 104 | 没有找到对应的数据 |
| 50000 | 接口频率受限(每个smsUser,每个接口、每分钟调用4000次，目前只限制投递回应) |
| SMSHook 错误码(statusCode) | 含义 |
|---|---|
| 410 | 处理失败, 手机号在全局拦截列表 |
| 420 | 处理失败, 手机号在局部拦截列表 |
| 430 | 处理失败, 取消订阅 |
| 440 | 处理失败, 关键词过滤 |
| 450 | 处理失败, 替换变量错误 |
| 460 | 处理失败, 短信内容不能超过500个字符 |
| 500 | 发送失败, 手机空号 |
| 510 | 发送失败, 手机停机 |
| 550 | 发送失败, 该模板内容被投诉 |
| 580 | 发送失败, 手机关机 |
| 590 | 发送失败, 其他原因 |