文档中心 > 新手指南 > 开发者协议
开发者协议

目录

  • ○ 重要通知
  • ○ 隐私条款
  • ○ 协议的更新及用户关注业务
  • ○ 使用规则
  • ○ 免责声明
  • ○ 法律管辖和适用
  • ○ 知识产权条款
  • ○ 服务终止
1. 重要需知

开发者应当同意本协议的条款并按照页面上的提示完成全部的注册程序。开发者一经注册或使用本协议下任何服务即视为对本服务条款的充分理解和完全接受。

（1）开发者注册成为189邮箱开放平台开发者，注册成功后，使用189邮箱开放平台产生的任何操作，均视为用户自身的行为，开发者应当对以其进行的所有活动和事件负法律责任。

（2）开发者可以使用平台提供的开放能力接口进行合作应用开发。当开发者使用平台提供的某个开放能力时，开发者的使用行为视为其对该开放能力的协议条款以及189邮箱开放平台各类公告的同意。

（3）189邮箱开放平台所提供开放能力的具体内容由189邮箱开放平台根据实际情况提供。除非本服务协议另有其它明示规定，189邮箱开放平台所推出的新能力、新功能、新服务，均受到本服务协议之规范。

（4）189邮箱开放平台基本协议以及各个频道单项技术服务条款和公告可由189邮箱开放平台随时更新，且无需另行通知。开发者在使用相关服务时,应关注并遵守其所适用的相关条款。

2.使用规则
（1）开发者在使用智能消息平台服务时，必须遵守中华人民共和国相关法律法规的规定，开发者承诺将不会利用本服务进行任何违法或不正当的活动。包括但不限于下列行为：

（a）反对宪法所确定的基本原则的；

（b）危害国家安全，泄露国家秘密，颠覆国家政权，破坏国家统一的；

（c）损害国家荣誉和利益的；

（d）煽动民族仇恨、民族歧视，破坏民族团结的；

（e）破坏国家宗教政策，宣扬邪教和封建迷信的；

（f）散布淫秽、色情、赌博、暴力、凶杀、恐怖或者教唆犯罪的；

（g）侮辱或者诽谤他人，侵害他人合法权益的；

（h）含有法律、行政法规禁止的其他内容的。

（i）含有中国法律、法规、规章、条例以及任何具有法律效力之规范所限制或禁止的其它内容的。

（2）开发者应保证其提交注册信息真实、有效。开发者的相关注册信息发生变化时，应当在变更后30个工作日内修改相关注册信息。由于开发者注册信息不准确或未及时更新导致的任何损失或责任由开发者自行承担。
（3）开发者负责其合作产品的创作、开发、编辑、加工、修改、测试、运营及维护，并且自行承担相应的成本。
（4）开发者保证不得以任何方式或企图干扰智能消息平台的任何部分、功能的正常运行。开发者违反上述条款，智能消息平台有权根据其情节，对开发者进行警告、限制服务、应用下线、应用删除、中止或终止服务等处罚。如因此给智能消息平台与关联公司及合作公司造成损失的，开发者应予以赔偿。
（5）开发者对自己在使用智能消息平台服务过程中的行为承担法律责任。开发者违反本协议或相关的服务条款的规定，导致或产生的任何第三方主张的任何索赔、要求或损失，开发者同意赔偿智能消息平台与关联公司及合作公司，并使之免受损害。
3.知识产权条款

智能消息平台上所有内容，包括但不限于著作、图片、档案、资讯、资料、网站架构、网站画面的安排、网页设计，均由智能消息平台或其他权利人依法拥有其知识产权。非经智能消息平台或其他权利人书面同意任何人不得擅自使用、修改、复制、公开传播、改变、散布、发行或公开发表智能消息平台网站程序或内容。

4.隐私条款
（1）智能消息平台重视对开发者隐私信息的保护，开发者在智能消息平台登记保留的个人资料将受到保护。智能消息平台使用安全技术和程序保护开发者个人信息不被未经授权的访问、使用或泄露。如发生下列任一情况，智能消息平台有权对开发者的信息予以披露：

（a）经相关开发者同意披露的；

（b）根据法律的有关规定，或者行政或司法机构的要求，向第三方或者行政、司法机构披露；

（c）如果开发者出现违反中国有关法律、法规、规章、政策的，需要向第三方披露；

（d）经相关开发者同意披露的；

（2）开发者在其应用设计上重视用户体验，尊重用户知情权、选择权，提供应用服务时应坚持诚信原则，不误导、欺诈、混淆用户，尊重用户的隐私，不骚扰用户，不制造垃圾信息。
5.免责声明
（1）鉴于网络服务的特殊性，开发者同意智能消息平台会变更、中断部分或全部的网络服务，智能消息平台将按相关管理规则通知开发者，智能消息平台不承担由此引起的任何责任。
（2）智能消息平台有权定期或不定期地对提供网络服务的平台或相关的设备进行检修或者维护，如因此类情况而造成网络服务在合理时间内的中断或暂停，智能消息平台无需为此承担任何责任。 如发生下述任一情况而导致服务中断及开发者损失的，智能消息平台不承担责任：

（a）发生不可抗力情形的；

（b）黑客攻击、计算机病毒侵入或发作的；

（c）计算机系统遭到破坏、瘫痪或无法正常使用的；

（d）因政府管制而造成暂时性关闭的；

（e）其它非因智能消息平台的过错而引起的。

6.服务终止
（1）在开发者违反本协议规定时，智能消息平台有权随时暂停或终止向该开发者提供全部开放平台服务。如该开发者后续再直接或间接或以他人名义注册并登录智能消息平台的，智能消息平台有权直接单方面暂停或终止提供本协议下服务。
（2）如本协议服务终止，智能消息平台有权保留或删除开发者账号中的任何信息和全部相关数据，包括服务终止前开发者尚未完成的任何数据。
7.协议的更新及用户关注义务
（1）根据国家法律法规变化及网站运营需要，智能消息平台有权对本协议条款不时地进行修改，修改后的协议一旦被张贴在本站上即生效，并代替原来的协议。用户可随时登录查阅最新协议；用户有义务不时关注并阅读最新版的协议及网站公告。如用户不同意更新后的协议，可以且应立即停止接受智能消息平台依据本协议提供的服务；如用户继续使用智能消息平台提供的服务的，即视为同意更新后的协议。智能消息平台建议您在使用服务之前阅读本协议的公告。 如果本协议中任何一条被视为废止、无效或因任何理由不可执行，该条应视为可分的且并不影响任何其余条款的有效性和可执行性。
（2）智能消息平台在法律允许的范围内对本协议及内容拥有解释权。
8.法律管辖和适用
本协议的订立、执行和解释及争议的解决均应适用在中华人民共和国大陆地区适用之有效法律（但不包括其冲突法规则）。 如发生本协议与适用之法律相抵触时，则这些条款将完全按法律规定重新解释，而其它有效条款继续有效。 如缔约方就本协议内容或其执行发生任何争议，双方应尽力友好协商解决；协商不成时，任何一方均可向本协议的履行地即广东省广州市天河区人民法院提起诉讼。
上一篇：接入流程 下一篇：邮件API
文档中心 > 新手指南 > 短信API
189邮箱开放平台接口流程规范

目录

  • ○ 范围
  • ○ 引用标准
  • ○ 缩略语
  • ○ 总体概述
  • ○ 接口规范
1 范围

本文档协议用于云消息平台与第三方公司的服务端应用进行数据交互，提供云消息平台的短信服务等基础能力。

2 引用标准

公网软件接口规范化1.0。

3 缩略语
名称 含义 作用
appSecret 云消息平台分配的key 第三方参数加密密钥
XXTea 小型的对称加密算法 对传入参数加密
JSON JavaScript Object Notation 种轻量级的数据交换格式
4 总体概述
4.1 通讯协议

短信服务采用HTTPS协议跟接入方交互，保证数据安全性，返回结果为JSON数据，详见每个接口说明。

4.2 数据格式

下面章节接口详细规范的请求参数说明中，如果与本章中定义的参数相同，只是为了描述，无需在加密参数串paras中重复设置。下面章节接口详细规范的请求参数说明中，如果没有特殊描述，都是说明非公共参数，即paras中需要加密的参数。

4.2.1 下行公共参数

服务支持以POST或GET方式提交数据，考虑到请参数长度可能受限，建议以POST方式提交。请求参数个数固定，如下表所述：

字段标识 说明 数据类型 长度 可空
appKey 开发者在注册应用的时候在云消息平台申请的接入方ID。 String 10 N
clientType 客户端类型。 String 8 N
format 目前仅支持json格式，redirect（用于重定向接口的显示说明）。 String 10 N
version 调用的接口版本号，默认v1.0，如v1.5 、v2.0。 String 5 N
paras 使用appSecret对所有传入参数采用XXTea加密，并且按照接口详细规范中定义的参数(除appKey、clientType、format、version、sign)拼接，不要求参数顺序。例如：paras = XXTea((a=value1&b=value2&…), appSecret))。 String N
sign 签名算法：
sign=HMAC-SHA1(appKey+clientType+format+version+paras,appSecret)。
备注：注意保持签名的各字段顺序正确。		 String 100 N
4.2.2 上行回执公共参数

服务支持以POST或GET方式提交数据，考虑到请参数长度可能受限，建议以POST方式提交。请求参数个数固定，如下表所述：

字段标识 说明 数据类型 长度 可空
appKey 开发者在注册应用的时候在189邮箱开放平台申请的接入方ID。 String 10 N
paras 使用appSecret对所有传入参数采用XXTea加密，并且按照接口详细规范中定义的参数(除appKey、sign)拼接，不要求参数顺序。例如：paras = XXTea((a=value1&b=value2&…), appSecret))。 String N
sign 签名算法：
sign=HMAC-SHA1(appKey+paras,appSecret)
备注：注意保持签名的各字段顺序正确。		 String 100 N
4.3 权限控制

1.接入方在接入短信服务时之前，需要登录189邮箱开放平台，需要申请接入appKey和appSecret，并由业务人员评估并分配需要使用的接口，所有接口调用通过appKey来识别接入方，并通过appSecret对传输的用户数据进行加密以确保调用安全。

2.申请appKey之前，需要在189邮箱开放平台中进行企业认证，认证通过后才可以进行appKey申请等后续操作。

3.用户申请appKey和appSecret之后，需要在平台上编辑自己的短信模板并提交审核，具体的步骤请详细见189邮箱开放平台开发者文档。

4.对于安全要求更高的接口，189邮箱开放平台要求只能通过服务端IP白名单鉴权来调用，IP白名单要求接入方在系统上线前告知189邮箱开放平台业务人员。

5 接口规范 5.1下行 5.1.1获取令牌接口 1. 能力介绍

获取令牌accessToken，短信能力使用时需要传入该参数，accessToken存在有效时间，应在失效时更新accessToken。

2. 接口定义
接口名称 accessToken
接口描述 提供获取令牌accessToken的能力
承载协议 HTTPS
承载网络 公网
请求方式 GET、POST
数据格式 请求参数以form表单形式提交，返回数据类型为：Json
约束
接口URL /auth/getAccessToken
测试环境：http://183.61.185.118:8082/sendApi/auth/getAccessToken
生产环境：https://ytx.21cn.com/sendApi/auth/getAccessToken
3. 非公共请求参数（paras中需要加密的参数）
字段标识 说明 数据类型 长度 可空
timeStamp 时间戳，毫秒 Long 18 N
4. 响应参数
字段标识 说明 数据类型 长度 可空
code 10000：成功， 其他：失败 Integer 6 N
msg 错误时返回错误信息 String 1024 N
timeStamp 时间戳yyyy-MM-dd HH:mm:ss，其中HH 取值为00-23，时区为东八区(接入方必须判断时间戳的有效性，以防重放攻击)。 String 19 N
appKey 开发者在注册应用的时候在智能消息平台申请的接入方ID。 String 10 N
accessToken 令牌 String 64 N
expiresIn accessToken的有效期，以秒为单位 Long 18 N
5.1.2 含变量的单封短信/邮件下发接口 1. 能力介绍

使用189邮箱开放平台中已经通过审核的短信或邮件模板，传入对应的变量，从而下发自定义内容的短信或邮件。模板中含有的变量必须全部填充，否则不允许下发。

2. 接口定义
接口名称 smv
接口描述 提供下发短信或邮件的能力
承载协议 HTTPS
承载网络 公网
请求方式 POST、GET
数据格式 请求参数以form表单形式提交，返回数据类型为：Json
约束
接口URL /send/smv
测试环境：http://183.61.185.118:8082/sendApi/send/smv
生产环境：https://ytx.21cn.com/sendApi//send/smv
3. 非公共请求参数（paras中需要加密的参数）
字段标识 说明 数据类型 长度 可空
requestId 请求ID，标识一次发信行为，相同请求ID不予下发 String <=16 N
ext 扩展号 String 1至7位 Y
timeStamp 时间戳，毫秒 Long 18 N
accessToken 令牌 String 64 N
type 发送类型：
type=1，单发短信
type=2，单发邮件
type=3，邮件发送后，生成短链并发短信		 Integer 1 N
email 收件人邮箱
type为2时必选
当type=3时，email为null，则邮箱为mobile+@189.cn		 String 60 Y
emailTemplateId 邮件模板ID
当type=2或3时，必选		 String 64 Y
mobile 短信接收方手机号
type=1或type=3，必选		 String 20 Y
smsTemplateId 短信模板ID
type=1或type=3，必选		 String 64 Y
data 模板对应的变量数据，JSON格式
说明：key:value形式，key为模板对应的变量，value为该变量对应的值
例子：
{
"name":"189邮箱",
"goods":"牛奶"
}		 String 2048 Y
4. 响应参数
字段标识 说明 数据类型 长度 可空
code 结果码。10000：成功， 其他：失败 Integer 6 N
msg 错误时返回错误信息 String 64 N
timeStamp 时间戳yyyy-MM-dd HH:mm:ss，其中HH 取值为00-23，时区为东八区(接入方必须判断时间戳的有效性，以防重放攻击)。 String 19 N
appKey 开发者在注册应用的时候在智能消息平台申请的接入方ID。 String 10 N
recordId 消息ID，该消息唯一标识，之后的回调会作为参数带上。 String 32 N
requestId 请求ID，标识一次发信行为，相同请求ID不予下发。 String <=20 N
5. 发送结果返回结果码表
code msg 含义
10000 send_ok 成功
-1001 param_illegal 参数校验错误
-1002 param_lack 缺少参数
-1003 invalid_request 无效请求
-1004 error_sign 签名错误
-1005 error_permission 无接口权限
-1006 invoked_frequent 调用过于频繁
-1007 system_exception 系统错误
-1008 ip_illegal 调用方ip不合法
-1009 token_illegal 调用方token不合法
-1010 sms_template_illegal 调用方使用的短信模板不存在或不合法
-1011 mail_template_illegal 调用方使用的邮件模板不存在或不合法
-1012 mobile_illegal 手机号不合法
-1013 email_illegal 邮箱不合法
-1014 content_illegal 内容未通过反垃圾扫描
-1015 sender_phone_illegal 下发端口不合法
-1016 appKey_illegal appKey不合法
-1017 clientType_illegal 调用方客户类型不合法
-1018 ext_illegal 同一个模板不能使用不同的扩展码
-1019 ext_occupied 扩展码已经被占用
-1020 ext_fail 扩展号分配失败
-1021 channel_illegal 通道配置有误
5.2 上行 5.2.1短信发送状态报告推送接口 1. 能力介绍

短信发送状态报告推送接口，使用方需在云通信配置短信发送状态报告推送接口地址。

2. 接口定义
接口名称 短信发送状态报告推送接口
接口描述 短信发送状态报告推送接口
承载协议 HTTP
承载网络 公网
请求方式 GET、POST
数据格式 请求参数以form表单形式提交，返回数据类型为：Json
约束
接口URL 用户自定义，在申请appKey时填充完善
3. 非公共请求参数（paras中需要加密的参数）
字段标识 说明 数据类型 长度 可空
timeStamp 时间戳，毫秒 Long 18 N
mobile 接收方手机号 String 20 N
code 发送状态 String 6 N
recordId 消息ID，该消息唯一标识，与发送接口返回的recordId对应。 String 32 N
sendTime 下发时间，时间戳，毫秒 Long 18 N
4. 响应参数

response status = 200表示成功，其它失败并重试。重试次数3次后，取消重试，并记录该次回调失败。

5. 发送状态报告码表
code 说明
200 发送成功
100 发送等待
-200 失败
-201 发送拒绝，内容未通过审核，黑名单，不须重试
-202 发送用户不存在
-100 变量数据有误
-101 requestId 重复，拒绝下发
-300 其它异常
-301 系统异常
5.2.2 邮件发送状态报告推送接口 1.能力介绍

邮件发送状态报告推送接口，使用方需在云通信配置邮件发送状态报告推送接口地址。

2.接口定义
接口名称 邮件发送状态报告推送接口
接口描述 邮件发送状态报告推送接口
承载协议 HTTP
承载网络 公网
请求方式 POST、GET
数据格式 请求参数以form表单形式提交，返回数据类型为：Json
约束
接口URL 用户自定义，在申请appKey时，需完善该接口地址。
3. 非公共请求参数（paras中需要加密的参数）
字段标识 说明 数据类型 长度 可空
timeStamp 时间戳，毫秒 Long 18 N
email 接收方邮箱 String 20 N
code 发送状态 String 6 N
recordId 消息ID，该消息唯一标识，与发送接口返回的recordId对应。 String 32 N
sendTime 下发时间，时间戳，毫秒。 Long 18 N
4. 响应参数

response status = 200表示成功，其它失败并重试。重试次数3次后，取消重试，并记录该次回调失败。

5. 发送状态报告码表
code 说明
200 成功
-200 失败
-100 数据有误
-101 requestId 重复，拒绝下发
-300 其它异常
-301 系统异常
5.2.3 短信上行回复推送接口 1. 能力介绍

短信上行回复推送接口，需在189邮箱开放平台设置推送接口地址。

2. 接口定义
接口名称 短信上行回复推送
接口描述 短信上行回复推送
承载协议 HTTP
承载网络 公网
请求方式 POST、GET
数据格式 请求参数以form表单形式提交，返回数据类型为：Json。
约束
接口URL 用户自定义
3.非公共请求参数（paras中需要加密的参数）
字段标识 说明 数据类型 长度 可空
timeStamp 时间戳，毫秒 Long 18 N
mobile 回复用户手机号 String 20 N
content 回复内容 String 255 N
receiveTime 接收时间，时间戳，毫秒 Long 18 N
ext 扩展号，数值 String 1至7位 Y
4. 响应参数

response status = 200表示成功，其它失败并重试。重试次数3次后，取消重试，并记录该次回调失败。