1. 首页
  2. 短信服务
  3. 短信产品接口文档
搜索ing...

短信产品接口文档

短信剩余量查询接口

接口地址

GET https://sms-api.upyun.com/api/users/remain

请求头

请求头参数 说明 Required（必填）
Authorization 授权 token ✔️

参数定义

无

响应

200 OK
{
  "industry": 50000,
  "marketing": 100000,
  "intl": 81,
  "idn": 0,
  "jpn": 100,
  "sgp": 100
}

响应值说明

参数 类型 说明
industry integer 行业短信剩余量
marketing integer 营销短信剩余量
intl integer 国际短信剩余量
idn integer 印尼短信剩余量
jpn integer 日本短信剩余量
sgp integer 新加坡短信剩余量

请求示例

GET https://sms-api.upyun.com/api/users/remain HTTP/1.1
Authorization: <your token>

短信模板新增接口

接口地址

POST https://sms-api.upyun.com/api/templates

请求头

请求头参数 说明 Required（必填）
Authorization 授权 token ✔️

参数定义

参数 类型 说明 Required（必填）
title string 模板标题(3 ~ 12个字符) ✔️
content string 模板内容（签名 + 内容 + 2 不大于 350 个字, 国际短信纯英文最多支持 420 个字符） ✔️
temp_sign string 模版签名（3 ～ 8个字, 国际短信无限制） ✔️
sign_location string 模版签名位置 (仅支持 top) ✔️
type string 模板类型 (行业: industry, 营销 marketing, 国际: intl, 日本: jpn, 印尼: idn, 新加坡: sgp) ✔️
report_type string 审核类型（仅支持 vip） ✔️

响应

创建成功返回响应码和内容。

201 Created
{
  "id": 4,
  "title": "title",
  "temp_sign": "sign",
  "content": "content",
  "sign_location": "top",
  "type": "industry",
  "status": "review",
  "updated_at": "2017-04-10T02:58:12.000Z",
  "report_type": "vip",
  "owner": {
    "id": 1,
    "name": "taevas",
    "industry": 4,
    "marketing": 0,
    "intl": 1,
    "idn": 0,
    "jpn": 0,
    "sgp": 0
  }
}

响应值说明

参数 类型 说明
title string 模板标题
temp_sign string 模板签名
content string 模板内容
status string 模板状态（review、success、defeat)
sign_location string 模版签名位置 (top)
type string 短信类型(行业: industry, 营销 marketing, 国际: intl, 日本: jpn, 印尼: idn, 新加坡: sgp)
updated_at string 更新时间
report_type string 审核类型（免签: vip）
id integer 模板编号
owner object 创建者信息
owner.id integer 用户编号
owner.name string 用户昵称
owner.industry integer 已发送行业短信条数
owner.marketing integer 已发送营销短信条数
owner.intl integer 已发送国际短信条数
owner.idn integer 已发送印尼短信条数
owner.jpn integer 已发送日本短信条数
owner.sgp integer 已发送新加坡短信条数

请求示例

POST https://sms-api.upyun.com/api/templates HTTP/1.1
Authorization: <your token>
{
  "title": "title",
  "content": "content",
  "temp_sign": "sign",
  "sign_location": "top",
  "type": "industry",
  "report_type": "vip"
}

短信模板删除接口

接口地址

DELETE https://sms-api.upyun.com/api/templates/{template_id}

请求头

请求头参数 说明 Required（必填）
Authorization 授权 token ✔️

参数定义

参数 说明 Required（必填）
template_id 模板编号 ✔️

响应

204 No Content

请求示例

DELETE https://sms-api.upyun.com/api/templates/4
Authorization: <your token>

短信模板修改接口

接口地址

PATCH /api/templates/{template_id}

请求头

请求头参数 说明 Required（必填）
Authorization 授权 token ✔️

参数定义

参数 类型 说明 Required（必填）
template_id integer 模板编号（url path 中代入） ✔️
title string 模板标题(3 ~ 12个字符)
content string 模板内容（签名 + 内容 + 2 不大于 350 个字, 国际短信纯英文最多支持 420 个字符）
temp_sign string 模版签名（3 ～ 8个字, 国际短信无限制）
sign_location string 模版签名位置 (top)

响应

200 OK
{
  "title": "hello",
  "temp_sign": "sign",
  "content": "content",
  "sign_location": "top",
  "type": "industry",
  "status": "review",
  "updated_at": "2017-04-10T03:31:18.000Z",
  "id": 3,
  "report_type": "vip",
  "owner": {
    "id": 1,
    "name": "taevas",
    "industry": 4,
    "marketing": 0,
    "intl": 1,
    "idn": 0,
    "jpn": 0,
    "sgp": 0
  }
}

响应值说明

参数 类型 说明
title string 模板标题
temp_sign string 模板签名
content string 模板内容
status string 模板状态（review、success、defeat)
sign_location string 模版签名位置 (top)
type string 短信类型(行业: industry, 营销 marketing, 国际: intl, 日本: jpn, 印尼: idn, 新加坡: sgp)
updated_at string 更新时间
report_type string 审核类型（免签: vip）
id integer 模板编号
owner object 创建者信息
owner.id integer 用户编号
owner.name string 用户昵称
owner.industry integer 已发送行业短信条数
owner.marketing integer 已发送营销短信条数
owner.intl integer 已发送国际短信条数
owner.idn integer 已发送印尼短信条数
owner.jpn integer 已发送日本短信条数
owner.sgp integer 已发送新加坡短信条数

请求示例

PATCH https://sms-api.upyun.com/api/templates/3
Authorization: <your token>
{
  "title": "hello"
}

查询模板接口

接口地址

GET https://sms-api.upyun.com/api/templates

请求头

请求头参数 说明 Required（必填）
Authorization 授权 token ✔️

参数定义

参数 说明 Required（必填）
type 模板类型 (行业: industry, 营销 marketing, 国际: intl, 日本: jpn, 印尼: idn, 新加坡: sgp)
report_type 审核类型（vip, general）

响应

200 OK
{
  "templates": [
    {
      "title": "hello",
      "temp_sign": "sign",
      "content": "content",
      "sign_location": "top",
      "type": "industry",
      "status": "review",
      "updated_at": "2017-04-10T03:31:18.000Z",
      "id": 3,
      "report_type": "vip",
      "owner": {
        "id": 1,
        "name": "taevas",
        "industry": 4,
        "marketing": 0,
        "intl": 1,
        "idn": 0,
        "jpn": 0,
        "sgp": 0
      }
    }
  ]
}

响应值说明

参数 类型 说明
title string 模板标题
temp_sign string 模板签名
content string 模板内容
status string 模板状态（review、success、defeat)
sign_location string 模版签名位置 (top)
type string 短信类型(行业: industry, 营销 marketing, 国际: intl, 日本: jpn, 印尼: idn, 新加坡: sgp)
updated_at string 更新时间
report_type string 审核类型（免签: vip）
id integer 模板编号
owner object 创建者信息
owner.id integer 用户编号
owner.name string 用户昵称
owner.industry integer 已发送行业短信条数
owner.marketing integer 已发送营销短信条数
owner.intl integer 已发送国际短信条数
owner.idn integer 已发送印尼短信条数
owner.jpn integer 已发送日本短信条数
owner.sgp integer 已发送新加坡短信条数

请求示例

GET https://sms-api.upyun.com/api/templates?type=industry&report_type=vip
Authorization: <your token>

短信发送接口

国内短信 / 国际短信以模板号区分

接口地址

POST https://sms-api.upyun.com/api/messages

请求头

请求头参数 说明 Required（必填）
Authorization 授权 token ✔️

参数定义

参数 类型 说明 Required（必填）
mobile string 手机号，逗号分隔 ✔️
template_id integer 模板编号（根据模板编号区分国内 / 国际短信） ✔️
vars string 短信参数（以 | 分隔）
variables array[string] 短信参数 [“变量 1”, “变量 2”], 优先于 vars
extend_code string 拓展码，自定义 3-6 位数字
sign string 自定义签名，传值后将覆盖模板自带的签名（需联系商务开启）

响应

200 OK
{
  "code":0,
  "message_ids": [
    {
      "report_code":"1004011",
      "error_code": "ILLEGAL_MOBILE",
      "mobile": "15757854321"
    },
    {
      "report_code":"0",
      "msg_id": "30",
      "mobile": "15757654321”
    }
  ]
}

响应值说明

参数 类型 说明
code string 一级返回码，0 为成功，其他返回码均为失败
message_ids array 所有手机号发送短信的结果
report_code string 二级返回码，0 为成功，其他详见错误码列表
error_code string 错误情况
message_id integer 旧版本国内短信的 message 编号（已弃用，改用 msg_id）
msg_id string message 编号
mobile string 手机号

请求示例

POST https://sms-api.upyun.com/api/messages
Authorization: <your token>
{
  "template_id": 2,
  "mobile": "15757854321,15757654321"
}

短信异步批量发送接口（文件形式）

国内短信 / 国际短信以模板号区分

接口地址

POST https://sms-api.upyun.com/api/messages/file

请求头

请求头参数 说明 Required（必填）
Authorization 授权 token ✔️
Content-type 内容包含文件, 编码方式建议 multipart/form-data

参数定义

参数 说明 Required（必填）
file 文件 ✔️
template_id 模板编号（根据模板编号区分国内 / 国际短信） ✔️
time 指定时间（三天内）发送, e.g. 2020-01-01 10:30:00

响应

202 Accepted

{
  "message": "OK", 
}

请求示例

curl -X POST \
https://sms-api.upyun.com/api/messages/file \
-H 'content-type: multipart/form-data' \
-F file=@/Desktop/mobile.csv \
-F template_id=1

短信异步批量发送接口（手机号形式）

国内短信 / 国际短信以模板号区分

接口地址

POST https://sms-api.upyun.com/api/messages/async

请求头

请求头参数 说明 Required（必填）
Authorization 授权 token ✔️

参数定义

参数 类型 说明 Required（必填）
mobile string 手机号，以 `,` 分隔 ✔️
template_id integer 模板编号（根据模板编号区分国内 / 国际短信） ✔️
time string 指定时间（三天内）发送, e.g. 2020-01-01 10:30:00
vars string 短信参数（以 | 分隔）
variables array[string] 短信参数 [“变量 1”, “变量 2”], 优先于 vars
extend_code string 拓展码，自定义 3-6 位数字
sign string 自定义签名，传值后将覆盖模板自带的签名（需联系商务开启）
custom string 可自定义字段，传值可用1，2，3

响应

202 Accepted
{
  "code": 0,
  "message": "OK",
  "id": "1"
}

请求示例

POST https://sms-api.upyun.com/api/messages/async
Authorization: <your token>
{
  "template_id": 2,
  "mobile": "15757654321,15757654322"
  "time": "2020-01-01 00:00:00"
}

短信异步批量发送接口（不同手机号，不同内容）

国内短信 / 国际短信以模板号区分

接口地址

POST https://sms-api.upyun.com/api/messages/async

请求头

请求头参数 说明 Required（必填）
Authorization 授权 token ✔️

参数定义

参数 类型 说明 Required（必填）
mobile string 数组内容 ✔️
template_id integer 模板编号（根据模板编号区分国内 / 国际短信） ✔️
time string 指定时间（三天内）发送, e.g. 2020-01-01 10:30:00
phone string 手机号 ✔️
variables array[string] 短信参数 [“变量 1”, “变量 2”] ✔️
extend_code string 拓展码，自定义 3-6 位数字
sign string 自定义签名，传值后将覆盖模板自带的签名（需联系商务开启）
custom string 可自定义字段，传值可用1，2，3

响应

202 Accepted
{
  "code": 0,
  "message": "OK",
  "id": "1"
}

请求示例

POST https://sms-api.upyun.com/api/messages/async
Authorization: <your token>
{
  "template_id": 2,
  "mobile": [
    {"phone": "17366645640","variables": ["变量1","变量2"],"sign": "又拍云"},
    {"phone": "15868150829","variables": ["变量1","变量2"],"sign": "又拍云科技"}
],
  "extend_code":"888888",
  "time": "2020-01-01 00:00:00"
}

短信报表查询接口

接口地址

GET https://sms-api.upyun.com/api/messages

请求头

请求头参数 说明 Required（必填）
Authorization 授权 token ✔️

参数定义

参数 说明 Required（必填）
date 日期（格式：YYYY-MM-DD，默认为当天）
mobile 手机号
status 消息发送的状态
page 页码（默认为 1）
per_page 每页显示数量（最大为 100，默认为 20）

响应

200 OK
{
  "messages": [
    {
      "id": 4,
      "template_id": 2,
      "report_type": "vip",
      "title": "测试测试",
      "type": "industry",
      "content": "hello，hello",
      "temp_sign": "落子時",
      "mobile": "15757654321”,
      "sent_at": null,
      "created_at": "2017-04-07T08:47:37.000Z",
      "status": "processing",
      "quantity": 1,
      "owner": {
        "id": 1,
        "name": "taevas",
        "industry": 4,
        "marketing": 0
      }
    }
    {
      "id": 2,
      "template_id": 2,
      "report_type": "vip",
      "title": "测试测试",
      "type": "industry",
      "content": "hello，hello【落子時】",
      "temp_sign": "落子時",
      "mobile": "15757123456”,
      "sent_at": "2017-04-06T08:36:01.000Z",
      "created_at": "2017-04-06T08:36:00.000Z",
      "status": "success",
      "quantity": 1,
      "owner": {
        "id": 1,
        "name": "taevas",
        "industry": 4,
        "marketing": 0
      }
    }
  ],
  "total": 2
}

响应值说明

参数 说明
id 短信编号
template_id 模板编号
report_type 审核类型
title 模板标题
type 短信类型(营销、行业)
content 模板内容
temp_sign 模板签名
mobile 手机号
sent_at 发送时间
created_at 创建时间
status 短信发送状态
owner 创建者信息
owner.id 用户编号
owner.name 用户昵称
owner.industry 已发送行业短信条数
owner.marketing 已发送营销短信条数

请求示例

curl -H "Authorization: <your token>" https://sms-api.upyun.com/api/messages?mobile=15757654321

国际短信报表查询接口

接口地址

GET https://sms-api.upyun.com/api/messages/intl

请求头

请求头参数 说明 Required（必填）
Authorization 授权 token ✔️

参数定义

参数 说明 Required（必填）
date 日期（格式：YYYY-MM-DD，默认为当天）
mobile 手机号（不需要 + 号）
status 消息发送的状态
page 页码（默认为 1）
per_page 每页显示数量（最大为 100，默认为 20）

响应

200 OK
{
  "messages": [
    {
      "id": "2020072816073510000001",
      "template_id": 3,
      "report_type": "vip",
      "title": "测试测试",
      "type": "industry",
      "content": "hello，hello",
      "temp_sign": "落子時",
      "mobile": "12345678912”,
      "sent_at": null,
      "created_at": "2020-07-28T16:07:35.000Z",
      "status": "processing",
      "quantity": 1,
      "owner": {
        "id": 1,
        "name": "taevas",
        "industry": 4,
        "marketing": 0,
        "intl": 2,
        "idn": 0,
        "jpn": 0,
        "sgp": 0
      }
    }
    {
      "id": "2020080101020310000001",
      "template_id": 3,
      "report_type": "vip",
      "title": "测试测试",
      "type": "industry",
      "content": "[落子時]hello，hello",
      "temp_sign": "落子時",
      "mobile": "12345678912",
      "sent_at": "2020-08-01T01:02:03.000Z",
      "created_at": "2020-08-01T01:02:03.000Z",
      "status": "success",
      "quantity": 1,
      "owner": {
        "id": 1,
        "name": "taevas",
        "industry": 4,
        "marketing": 0,
        "intl": 2,
        "idn": 0,
        "jpn": 0,
        "sgp": 0
      }
    }
  ],
  "total": 2
}

响应值说明

参数 类型 说明
id string 短信编号
template_id integer 模板编号
report_type string 审核类型
title string 模板标题
type string 短信类型(intl / jpn / sgp / idn)
content string 模板内容
temp_sign string 模板签名
mobile string 手机号
sent_at string or null 发送时间
created_at string 创建时间
status string 短信发送状态
owner object 创建者信息
owner.id integer 用户编号
owner.name string 用户昵称
owner.industry integer 已发送行业短信条数
owner.marketing integer 已发送营销短信条数
owner.intl integer 已发送国际短信条数
owner.sgp integer 已发送新加坡短信条数
owner.jpn integer 已发送日本模板短信条数
owner.idn integer 已发送印尼模板短信条数

请求示例

curl -H "Authorization: <your token>" https://sms-api.upyun.com/api/messages?mobile=15757654321

短信回调接口

说明

上行回调：用于接收短信回复的回调，回调内容主要是客户回复的文本，例如：TD，T，好的…等。国际短信无上行回调

下行回调：用于接收短信发送情况的回调，回调内容主要是短信发送成功，失败及失败的 code

使用方法

短信回调接口需要客户在控制台中添加回调 URL，路径为【控制台】-【模板】-【回调地址】

请求方式：HTTP-POST

编码格式：UTF-8

特殊说明：该接口失败重试次数为 5 次，重试间隔为 5 分钟

上行回调-发送给客户的格式

name type description
message_id integer 国内短信报表编号
content string 上行回调的内容
mobile string 信息发送到的手机号
receive_time integer 用户接收到的时间戳
template_id string 模板编号
extend_code string 拓展码 
// POST https://www.xxx.com HTTP/1.1
// Content-Type: application/json; charset=utf-8

{
    "message_id": 11,
    "template_id": 12,
    "content": "退订",
    "receive_time": 1588040220,
    "mobile": "18106636718"
}

下行回调-发送给客户的格式

name type description
id integer 国内短信报表编号
msg_id string 国际短信报表编号
task_id string 短信群发任务编号
quantity integer 短信计费条数
mobile string 信息发送到的手机号
receive_time integer 用户接收到的时间戳
report_status string 发送状态（success、defeat）
report_code string 报表状态码
custom string 自定义字段 
// POST https://www.xxx.com HTTP/1.1
// Content-Type: application/json; charset=utf-8

{
    "id": 1, // 仅国内短信使用
    "msg_id": "2020080101020310000001" // 仅国际短信使用
    "task_id":"10222",
    "mobile": "18106635188",
    "quantity": 10,
    "receive_time": 1586830985,
    "report_status": "success",
    "report_code": "DELIVRD",
    "custom": "1",
}

客户响应确认格式

name type description
result string 成功接收， 响应 “success” 
// HTTP/1.1 200 OK
// Content-Type: application/json

{
    "result": "success"
}

号码检测接口

接口地址

POST https://sms-api.upyun.com/api/detection/mobile

请求头

请求头参数 说明 Required（必填）
Authorization 授权 token ✔️

参数定义

参数 说明 type Required（必填）
mobile 11 位的有效手机号，以 , 分隔, 最大手机号数目为 100 个 string ✔️

请求示例

POST https://sms-api.upyun.com/api/detection/mobile HTTP/1.1
Authorization: <your token>
{
  "mobile": "15757854321,15757654322”
}

响应

200 OK
{
  "id": 1,
  "owner_id": 1,
  "mobiles": [
    13555555555
  ],
  "sum": 1,
  "data": [{
    "phoneStatus":5,
    "carrier":3,
    "phone":13555555555,
    "province":"浙江省",
    "city":"杭州市",
    "phoneStatusStr":"沉默号",
    "carrierStr":"电信"
  }],
  "count": 1,
  "created_at": 1592461187,
  "date": "2020-06-18",
  "done_time": 1592461187
}

响应值说明

参数 类型 说明
id int 任务编号
owner_id int 用户编号
mobiles bigint[] 手机号列表
sum int 手机号数目
data object 已完成的任务
phoneStatus int 手机号码状态标识号,参见手机号码状态标识号
carrier int 运营商标识号, 参见运营商标识号
phone bigint 手机号码
province string 号码归属地省份信息
city string 号码归属地城市信息,目前接口不支持地级市，有则返回，无则为空（null）
phoneStatusStr string 号码状态详情
carrierStr string 归属运营商详情
count int 已完成的任务数目
created_at int 创建时间
date string 日期， 格式 YYYY-MM-DD
done_time int 完成的时间戳
运营商标识号
标识号 描述
1 移动
2 联通
3 电信
手机号码状态标识号
标识号 描述
1 空号
2 实号
3 停机
4 库无
5 沉默号
6 风险号
7 错误号

这篇文章有帮助吗?

Yes No

相关文章