腾讯企业邮箱开放协议,包括面向第三方合作应用和面向企业邮用户两类。其中,面向企业邮用户的开放协议,将提供给企业邮用户丰富的应用接口,用户可以根据这些接口定制自己统一的企业解决方案。
通过协议接口,企业用户可以实现:
1. 同步成员帐号信息
2. 获取新邮件个数
3. 新邮件提醒
4. 单点登陆
接入流程如下:
图1 申请接入腾讯企业邮开放协议流程图
1. 用户需要以管理员身份登陆,并提交相关资料申请接入企业邮。提供资料内容包含如下资料:
• 如需要接入单点登陆,需提供:服务器IP和端口,验证uri。
• 如需要接入新邮件提醒,需提供:服务器IP和端口,接收uri。
2. 用户提交资料后,企业邮系统会对提交的资料进行验证,通过后会给用户发放app_id和app_secret。app_id用于唯一标识用户,app_secret用于对请求签名,可以验证请求合法性。
3. 用户根据appId和appSecret进行身份验证,得到access_token。
4. 根据access_token,同步数据。
协议采用HTTPS+JSON格式,请求采用GET/POST方式。
调用方需采用HTTPS调用请求,防止消息被窃取。
对于下发的请求,需要加上IP来源限制,以保证来源合法性。
1) 涉及到的字符均用UTF-8编码
根据申请到的app_id和app_secret,采用ClientCredentials方式获取access_token。
请求示例如下:
POST https://exmail.qq.com/cgi-bin/token HTTP /1.1 Host: exmail.qq.com Content-Length: 75 grant_type=client_credentials&client_id=biz0876xa&client_secret=yuw_0dfuxUa |
或者:
POST https://exmail.qq.com/cgi-bin/token HTTP /1.1 Host: exmail.qq.com Authorization: Basic Yml6MDg3NnhhOnl1d18wZGZ1eFVh Content-Length: 29 grant_type=client_credentials |
如果验证通过,返回:
{ "access_token":"jIFA9ju6v5XP", "token_type":"Bearer", "expires_in":86400, "refresh_token":"" } |
同步接口需要先经过OAuth验证,获取到access_token。调用的接口需要把参数access_token传过来。有两种方式,一种是在HTTP HEAD加上Authorization,另外一种是在GET/POST请求加上access_token
请求示例如下:
POST https://exmail.qq.com/openapi/user/get HTTP /1.1 Host: exmail.qq.com Content-Length: 45 |
或者:
POST https://exmail.qq.com/openapi/user/get HTTP /1.1 Host: exmail.qq.com Authorization: Bearer jIFA9ju6v5XP Content-Length: 19 |
openapi/user/get
请求字段:
字段 |
含义 |
Alias |
帐号名 |
返回data包含字段:
字段 |
含义 |
Alias |
帐号名 |
Name |
姓名 |
Gender |
性别:1=男,2=女 |
Position |
职位 |
Tel |
联系电话 |
Mobile |
手机 |
ExtId |
编号 |
PartyList |
部门列表 |
示例:
POST https://exmail.qq.com/openapi/user/get HTTP /1.1 Host: exmail.qq.com Authorization: Bearer jIFA9ju6v5XP Content-Length: 19 |
返回:
{ "Alias":"[email protected]", "Name":"鲍勃", "Gender":1, "Position":"工程师", "Tel":"60536", "Mobile":"", "ExtID":"810821", "PartyList": { "Count":2 "List": [ {"Value": "部门a"}, {"Value": "部门B/部门b"} ] } } |
注:
1)部门的根结点不包括在路径里面。比如部门所属:腾讯/广州研发中心/企业邮箱,Value为:广州研发中心/企业邮箱
openapi/user/sync
请求字段:
字段 |
含义 |
Action |
1=DEL, 2=ADD, 3=MOD |
Alias |
帐号名 |
Name |
姓名 |
Gender |
性别:1=男,2=女 |
Position |
职位 |
Tel |
联系电话 |
Mobile |
手机 |
ExtId |
编号 |
Password |
密码,明文。仅在ADD时需要。 |
返回data为空。通过返回状态码,判断是否调用成功。
示例:
POST https://exmail.qq.com/openapi/user/sync HTTP /1.1 Host: exmail.qq.com Authorization: Bearer jIFA9ju6v5XP Content-Length: 19 [email protected]&name=BOB&gender=1&position=engineer |
openapi/user/list
请求字段:
字段 |
含义 |
Ver |
版本号;初始=0表示获取全部帐号;如指定版本号,则取该版本号之后的变更记录 |
返回data包含字段:
字段 |
含义 |
Ver |
最新版本号;初始=0表示获取全部帐号 |
Count |
成员个数 |
List |
成员帐号列表 |
字段 |
含义 |
Action |
更新动作类型,1=Add, 2=Edit, 3=Del |
Alias |
帐号名 |
Name |
姓名 |
Gender |
性别:1=男,2=女 |
Position |
职位 |
Tel |
联系电话 |
Mobile |
手机 |
ExtId |
编号 |
请求示例:
POST https://exmail.qq.com/openapi/user/list HTTP /1.1 Host: exmail.qq.com Authorization: Bearer jIFA9ju6v5XP Content-Length: 19 Ver=1346600000000 |
返回:
{ "Ver": 1346674693912, "Count": 1, "List": [ { "Action": 3, "Alias": "[email protected]", "Name": "BOB", "Gender": 1, "Position": "engineer", "Tel": "", "Mobile": "", "ExtID": "", } ] } |
openapi/mail/newcount
请求字段:
字段 |
含义 |
Alias |
帐号名 |
返回data包含字段:
字段 |
含义 |
Alias |
姓名 |
NewCount |
新邮件数 |
openapi/slave/sync
请求字段:
字段 |
含义 |
Alias |
帐号名 |
Action |
更新动作类型,1=DEL, 2=ADD, 3=MOD |
Slave |
别名1 |
Slave |
别名2 |
示例:
POST https://exmail.qq.com/openapi/slave/sync HTTP /1.1 Host: exmail.qq.com Authorization: Bearer jIFA9ju6v5XP Content-Length: 48 |
openapi/party/sync
请求字段:
字段 |
含义 |
Action |
更新动作类型,1=DEL, 2=ADD, 3=MOD |
SrcPath |
源部门 (注: 部门用 '/' 分隔 根部门不用加 部门最多5级 单个部门字符不超过64个字符) |
DstPath |
目标部门 |
注:
2)如果DEL/ADD,则只需要传DstPath
3)如果MOD,需要将SrcPath,和DstPath传过来
openapi/partyuser/sync
请求字段:
字段 |
含义 |
Action |
更新动作类型,1=DEL, 2=ADD, 3=MOD |
Alias |
帐号名 |
PartyPath |
部门路径1 |
PartyPath |
部门路径2 |
openapi/party/list
请求字段:
字段 |
含义 |
PartyPath |
查看的父亲部门路径。如果查看根部门,置为空。 |
返回data包含字段:
字段 |
含义 |
Count |
部门总数 |
List |
部门列表 |
字段 |
含义 |
Value |
子部门名称 |
注:返回的子部门不进行迭代遍历,只是最近的一层子部门列表。
openapi/partyuser/list
请求字段:
字段 |
含义 |
PartyPath |
查看的父亲部门路径。如果查看根部门,置为空。 |
返回data包含字段:
字段 |
含义 |
Count |
部门总数 |
List |
部门列表 |
字段 |
含义 |
Value |
帐号名称 |
由接入方提供接入提醒的服务地址,
消息格式字段:
字段 |
含义 |
UserName |
帐号名 |
MailId |
邮件Id |
Sender |
发件人 |
Receiver |
收件人 |
Subject |
标题 |
Summary |
摘要 |
NewCount |
新邮件数 |
由企业邮下发更新提醒
消息格式字段:
字段 |
含义 |
UserName |
帐号名 |
NewCount |
新邮件列表 |
登陆采用SSO单点登陆方式,目前支持CAS验证和BizSSO方式。
https://exmail.qq.com/cgi-bin/login?fun=bizopenssologin&method= |
通过method指定验证方式,method=[cas|bizsso]。
CAS是Web上实现单点登陆的一种通用的方式。
1. 3rd OA表示接入方OA系统;3rd SSO表示接入方单点登录认证系统;user表示请求用户或是浏览器;bizmail表示腾讯企业邮箱。
2. ticket由接入方分派,具体要求:
a) 随机生成,长度不小于16个字符。
b) 接入方保证其有效性(ticket存储,认证,时效)。
c) 一个ticket只能对应一个user。同时确保ticket在一段时间内必须唯一(最少1年),而且一个ticket只能验证一次,防止被窃取ticket登录。
1. ticket验证采用 http post方式,由合作方提供ticket验证的URL。
2. 接入方必须保存ticket的session信息。
3. bizmail这边发出的请求会通过固定的代理服务器IP连接合作方服务器,合作方需将bizmail的代理服务器IP加入IP白名单;同时只允许来自IP白名单的验证请求。
http post content格式如下:
|
http 返回的content格式为:
|
1 result 只能是true或者false
2 username与ticket对应