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

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

1. 开放协议简介

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

通过协议接口,企业用户可以实现:

1. 同步成员帐号信息

2. 获取新邮件个数

3. 新邮件提醒

4. 单点登陆

2. 接入流程

接入流程如下:

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

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

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

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

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

3. 用户根据appIdappSecret进行身份验证,得到access_token

4. 根据access_token,同步数据。

3. 协议框架

3.1 协议格式

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

3.2 安全机制

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

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

3.3 其它约定

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

4. OAuth验证授权

根据申请到的app_idapp_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

[email protected]

或者:

POST https://exmail.qq.com/openapi/user/get HTTP /1.1

Host: exmail.qq.com

Authorization: Bearer jIFA9ju6v5XP

Content-Length: 19

[email protected]

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

[email protected]

返回:

{

"Alias":"[email protected]",

"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

[email protected]&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": "[email protected]",

"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

[email protected][email protected]

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=&agent=&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. 接入方必须保存ticketsession信息。

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

7.2.3 ticket验证request

http post content格式如下:

ValidateTicket

7.2.4 ticket验证response

http 返回的content格式为:

ValidateTicket

1  result  只能是true或者false

2  usernameticket对应

你可能感兴趣的:(腾讯企业邮箱接口说明文档)