腾讯企业邮箱接口说明文档

http://download.csdn.net/my/uploads/1

1. 开放协议简介

腾讯企业邮箱开放协议，包括面向第三方合作应用和面向企业邮用户两类。其中，面向企业邮用户的开放协议，将提供给企业邮用户丰富的应用接口，用户可以根据这些接口定制自己统一的企业解决方案。

通过协议接口，企业用户可以实现：

1. 同步成员帐号信息

2. 获取新邮件个数

3. 新邮件提醒

4. 单点登陆

2. 接入流程

接入流程如下：

图1 申请接入腾讯企业邮开放协议流程图

1. 用户需要以管理员身份登陆，并提交相关资料申请接入企业邮。提供资料内容包含如下资料：

• 如需要接入单点登陆，需提供：服务器IP和端口，验证uri。

• 如需要接入新邮件提醒，需提供：服务器IP和端口，接收uri。

2. 用户提交资料后，企业邮系统会对提交的资料进行验证，通过后会给用户发放app_id和app_secret。app_id用于唯一标识用户，app_secret用于对请求签名，可以验证请求合法性。

3. 用户根据appId和appSecret进行身份验证，得到access_token。

4. 根据access_token，同步数据。

3. 协议框架

3.1 协议格式

协议采用HTTPS+JSON格式，请求采用GET/POST方式。

3.2 安全机制

调用方需采用HTTPS调用请求，防止消息被窃取。

对于下发的请求，需要加上IP来源限制，以保证来源合法性。

3.3 其它约定

1) 涉及到的字符均用UTF-8编码

4. OAuth验证授权

根据申请到的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":"" }

5. 同步Api接口

同步接口需要先经过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 access_token=jIFA9ju6v5XP&alias=bob@gzdev.com

或者：

POST https://exmail.qq.com/openapi/user/get HTTP /1.1 Host: exmail.qq.com Authorization: Bearer jIFA9ju6v5XP Content-Length: 19 alias=bob@gzdev.com

5.1 获取成员资料

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=bob@gzdev.com

返回：

{ "Alias":"bob@gzdev.com", "Name":"鲍勃", "Gender":1, "Position":"工程师", "Tel":"60536", "Mobile":"", "ExtID":"810821", "PartyList": { "Count":2 "List": [ {"Value": "部门a"}, {"Value": "部门B/部门b"} ] } }

注：

1）部门的根结点不包括在路径里面。比如部门所属：腾讯/广州研发中心/企业邮箱，Value为：广州研发中心/企业邮箱

5.2 同步成员帐号资料

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 action=3&alias=bob@gzdev.com&name=BOB&gender=1&position=engineer

5.3 获取某个版本号后的用户更新列表

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": "bob@gzdev.com", "Name": "BOB", "Gender": 1, "Position": "engineer", "Tel": "", "Mobile": "", "ExtID": "", } ] }

5.4 获取新邮件数

openapi/mail/newcount

请求字段：

字段	含义
Alias	帐号名

返回data包含字段：

字段	含义
Alias	姓名
NewCount	新邮件数

5.5 同步别名

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 alias=bob@gzdev.com&action=1&slave=101@gzdev.com

5.6 同步部门

openapi/party/sync

请求字段：

字段	含义
Action	更新动作类型，1=DEL, 2=ADD, 3=MOD
SrcPath	源部门 （注： 部门用 '/' 分隔 根部门不用加 部门最多5级 单个部门字符不超过64个字符）
DstPath	目标部门

注：

2）如果DEL/ADD，则只需要传DstPath

3）如果MOD，需要将SrcPath，和DstPath传过来

5.7 调整成员所属部门

openapi/partyuser/sync

请求字段：

字段	含义
Action	更新动作类型，1=DEL, 2=ADD, 3=MOD
Alias	帐号名
PartyPath	部门路径1
PartyPath	部门路径2

5.8 获取子部门列表

openapi/party/list

请求字段：

字段	含义
PartyPath	查看的父亲部门路径。如果查看根部门，置为空。

返回data包含字段：

字段	含义
Count	部门总数
List	部门列表

字段	含义
Value	子部门名称

注：返回的子部门不进行迭代遍历，只是最近的一层子部门列表。

5.9 获取部门下成员列表

openapi/partyuser/list

请求字段：

字段	含义
PartyPath	查看的父亲部门路径。如果查看根部门，置为空。

返回data包含字段：

字段	含义
Count	部门总数
List	部门列表

字段	含义
Value	帐号名称

6. 新邮件/未读数下发提醒

由接入方提供接入提醒的服务地址，

6.1 新邮件提醒

消息格式字段：

字段	含义
UserName	帐号名
MailId	邮件Id
Sender	发件人
Receiver	收件人
Subject	标题
Summary	摘要
NewCount	新邮件数

6.2 未读数更新

由企业邮下发更新提醒

消息格式字段：

字段	含义
UserName	帐号名
NewCount	新邮件列表

7. 单点登陆接入

登陆采用SSO单点登陆方式，目前支持CAS验证和BizSSO方式。

https://exmail.qq.com/cgi-bin/login?fun=bizopenssologin&method=<method>&agent=<agent>&ticket=<ticket>

通过method指定验证方式，method=[cas|bizsso]。

7.1 CAS验证

CAS是Web上实现单点登陆的一种通用的方式。

7.2 BizSSO验证

7.2.1说明

1. 3rd OA表示接入方OA系统；3rd SSO表示接入方单点登录认证系统；user表示请求用户或是浏览器；bizmail表示腾讯企业邮箱。

2. ticket由接入方分派，具体要求：

a) 随机生成，长度不小于16个字符。

b) 接入方保证其有效性（ticket存储，认证，时效）。

c) 一个ticket只能对应一个user。同时确保ticket在一段时间内必须唯一（最少1年），而且一个ticket只能验证一次，防止被窃取ticket登录。

7.2.2 ticket验证

1. ticket验证采用 http post方式，由合作方提供ticket验证的URL。

2. 接入方必须保存ticket的session信息。

3. bizmail这边发出的请求会通过固定的代理服务器IP连接合作方服务器，合作方需将bizmail的代理服务器IP加入IP白名单；同时只允许来自IP白名单的验证请求。

7.2.3 ticket验证request

http post content格式如下：

<function> <name>ValidateTicket</name> <request> <ticket></ticket> </request> </function>

7.2.4 ticket验证response

http 返回的content格式为：

<function> <name>ValidateTicket</name> <response> <result></result> <username></username> </response> </function>

1  result  只能是true或者false

2  username与ticket对应