腾讯企业邮箱OpenApi调用说明
笔者最近在调用腾讯企业邮箱的接口，但因为项目使用的是2016年的老接口，不是新接口（https://exmail.qq.com/qy_mng_logic/doc#10001）
因此找到了之前的老接口文档供自己和大家参考。
一、开放协议介绍
- 1.1 功能简介
腾讯企业邮箱开放协议，包括面向第三方合作应用和面向企业邮用户两类。其中，面向
企业邮用户的开放协议，将提供给企业邮用户丰富的应用接口，用户可以根据这些接口定制己统一的企业解决方案。
通过协议接口，企业用户可以实现：
- 单点登录
可以从公司OA 系统、网站一键进入企业邮箱，免去登录过程。 - 新邮件提醒
新邮件将即时在OA 等办公系统提醒你。 - 数据同步
数据同步可以帮助你同步部门成员信息，你还可以创建、删除、修改帐号，同步部门信息等。
-
1.2 协议格式
协议采用HTTP+JSON 格式，请求采用GET/POST 方式。 -
1.3 安全机制
- 管理员在管理端可以随时启用/关闭同步选项。
- 在管理端的“操作记录”可以查询同步日志，方便观察异常。
- 1.4 协议编码
均用UTF-8 编码。
二、接入流程
接入腾讯企业邮开放接口的全流程图如下：
- 2.1 管理端申请
从链接http://exmail.qq.com 进入，使用管理员账号登录进入管理页面，打开“工具箱->开放议”，点击“立即申请”。
- 2.2 获取接口key
接口key，是作为下一步OAuth 验证授权传递的参数，需要查看明文。
（1）点击“查看明文”：
（2）输入管理员密码，点击“确定”
（3）可查看接口key
截图中的接口key 为563a8c6a89d2368194c1c7889c508b34
- 2.3 OAuth 验证授权
接口说明：
目前，腾讯企业邮箱采用OAuth2.0 协议对第三方进行授权，关于OAuth2.0 的详细介绍，请考OAuth 协议标准。
客户端通过长连接维持在线状态，服务端通过检查用户的在线状态，实时推送消息；同时客端根据同一个连接，获取请求数据。
调用的方式有两种方式：
POST 方式：在POST 请求加上access_token；
GET 或者其他方式：在HTTP HEAD 加上Authorization，将client_id 和client_secret 以
BASE64 加密方式加密，即base64(client_id: client_secret)，将密文发送到请求信息中。
1、URL：https://exmail.qq.com/cgi-bin/token
2、格式：JSON
3、HTTP 请求方式：GET/POST
4、输入参数说明：
参数名称类型描述
client_id string 当前管理员帐号
client_secret string 接口key
5、请求示例：
请求的参数：
client_id：swanzhong
client_secret：563a8c6a89d2368194c1c7889c508b34
POST https://exmail.qq.com/cgi-bin/token HTTP /1.1
Host: exmail.qq.com
Content-Length: 75
grant_type=client_credentials&client_id=swanzhong&client_secret=563a8c6a89d2368194c1c7889c50b34
或者：
请求的参数：
client_id：swanzhong
client_secret：563a8c6a89d2368194c1c7889c508b34
POST https://exmail.qq.com/cgi-bin/token HTTP /1.1
Host: exmail.qq.com
Authorization: Basic c3dhbnpob25nOjU2M2E4YzZhODlkMjM2ODE5NGMxYzc4ODljNTA4YjM0
Content-Length: 29
grant_type=client_credentials
6、返回参数说明：
参数名称描述
access_token
token_type
expires_in access_token 的有效使用期，失效后请重新获取
refresh_token
7、正确返回示例：
{
“access_token”:“GHUSH-4qIXPScxa_OY0CbPS31W1OM24L_Ys9FCc7LtJyxjHD5OZafLh3Y8
gM7gzDtp-GdQEY4dwFXk2qgnkwJA “,
“token_type”:“Bearer”,
“expires_in”:86400,
“refresh_token”:””
}
- 2.4 调用接口Api（客户端请求）
经过OAuth 授权验证后，获取到access_token，开发者可以根据实现功能的需要去选择调用API。以下章节将列出接口API 的功能和调用方式。
三、调用接口API 说明
接口API 能实现的功能有如下三个：
（1）单点登录：
可以从公司OA 系统、网站一键进入企业邮箱，免去登录过程。
（2）新邮件提醒：
新邮件将即时在OA 等办公系统提醒你。
（3）同步
数据同步可以帮助你同步部门成员信息，你还可以创建、删除、修改帐号，同步部门信息等。
- 3.1 单点登录
可以从公司OA 系统、网站一键进入企业邮箱，免去登录过程。接入流程图如下所示：
3.1.1 获取Authkey
接口说明：
1、URL：openapi/mail/authkey
2、格式：JSON
3、HTTP 请求方式：GET/POST
4、输入参数说明：
参数名称类型描述
Alias string 帐号名
5、请求示例：
请求参数：[email protected]
POST http://openapi.exmail.qq.com:12211/openapi/mail/authkey HTTP /1.1
Host: openapi.exmail.qq.com
Authorization: Bearer GHUSH-4qIXPScxa_OY0CbPS31W1OM24L_Ys9FCc7LtJyxjHD5OZafLh3Y
8gM7gzDtp-GdQEY4dwFXk2qgnkwJA
Content-Length: 19
[email protected]
6、返回参数说明：
参数名称描述
AuthKey 登陆/读信验证Key
7、正确返回示例：
{
“AuthKey”:
"077FFF01B4D6A28A07A21682C3C0D4FE04221261CE2E3FAFA9E8432937DCF57290EA36BAD
05815167251FF690134EDE4F40055B1B7B68C1D "
}
3.1.2 一键登录
接口说明：
1、URL：
2、格式：JSON
3、HTTP 请求方式：GET/POST
4、输入参数说明：
参数名称类型描述
ticket string 调用“获取Authkey”获
取的Authkey
agent string 管理员帐号
5、请求示例：
https://exmail.qq.com/cgi-bin/login?fun=bizopenssologin&method=bizauth&agent=&user=&ticket=
6、返回参数说明：
参数名称描述
mailid 服务器推送新邮件时的mailid 字段
7、正确返回示例
- 3.2 邮件提醒
新邮件将即时在OA 等办公系统提醒你。接入的流程图如下：
3.2.1 客户端维持长连接
调用说明：
调用此api 是用于维持客户端与服务器的长连接。
1、URL：openapi/listen
2、格式：JSON
3、HTTP 请求方式：GET/POST
4、输入参数说明：
参数名称类型描述
Ver string 本地维护的最新版本号
5、请求示例（初始版本号设置为0）：
POST http://openapi.exmail.qq.com:12211/openapi/listen HTTP /1.1
Host: openapi.exmail.qq.com
Authorization: Bearer
GHUSH-4qIXPScxa_OY0CbPS31W1OM24L_Ys9FCc7LtJyxjHD5OZafLh3Y8gM7gzDtp-GdQEY4d
wFXk2qgnkwJA
Content-Length: 19
Ver=1386593148546
6、返回参数说明：
如果当前客户端长连接在线，会返回参数“Ret”，当服务端检查到服务器版本号数据变更时，发最新版本号“ver”。
参数名称描述
Ret 返回值
7、正确返回示例：
{
“Ret”: 0
}
3.2.2 下发数据
如果当前客户端长连接在线，当服务端检查到数据变更时，将会下发数据：版本号更新；新
邮件提醒；实时更新未读邮件数。
（1）版本号更新
1、下发字段：
参数名称类型描述
Ver string 服务器最新版本号
2、下发示例：
{
“Ver”: “1364460338051”,
}
（2）新邮件提醒
1、下发字段：
参数名称描述
UserName 帐号名
MailId 邮件Id
Sender 发件人
Receiver 收件人
Subject 标题
Summary 摘要
NewCount 新邮件数
2、下发示例：
{
“UserName”: "[email protected]",
“MailId”: “ZC4028-FPiX_oOG5HUh4XorwyhAY33”,
“Sender”: ““Test” [email protected]”,
“Receiver”: "[email protected]",
“Subject”: “TestMail”,
“Summary”: "TestMail Content ",
“NewCount”: 549
}
（3）实时更新未读邮件数
1、下发字段：
参数名称描述
UserName 帐号
NewCount 未读邮件数
2、下发示例：
{
" UserName": "[email protected]",
" NewCount ": 550,
}
- 3.3 数据同步
数据同步可以帮助你同步部门成员信息，你还可以创建、删除、修改帐号，同步部门信息等。
接入的流程图如下：
3.3.1 获取成员资料
接口说明：
1、URL：openapi/user/get
2、格式：JSON
3、HTTP 请求方式：GET/POST
4、输入参数说明：
参数名称类型描述
Alias string 当前管理员帐号
5、请求示例：
POST http://openapi.exmail.qq.com:12211/openapi/user/get HTTP /1.1
Host: openapi.exmail.qq.com
Authorization: Bearer GHUSH-4qIXPScxa_OY0CbPS31W1OM24L_Ys9FCc7LtJyxjHD5OZafLh3Y8
gM7gzDtp-GdQEY4dwFXk2qgnkwJA
Content-Length: 25
alias= [email protected]
6、返回参数说明：
参数名称描述
Alias 帐号名
Name 姓名
Gender 性别：0=未设置，1=男，2=女
SlaveList 别名列表，用逗号分隔
Position 职位
Tel 联系电话
Mobile 手机
ExtId 编号
PartyList 部门列表，部门的根结点不包括在路径里面。比如部门所属：腾
讯/广州研发中心/企业邮箱，Value 为：广州研发中心/企业邮箱
OpenType 成员状态：1=启用，2=禁用
7、正确返回示例：
{
“Alias”: " [email protected]",
“Name”: “鲍勃”,
“Gender”: 1,
“SlaveList”: "[email protected],[email protected]",
“Position”: “工程师”,
“Tel”: “62394”,
“Mobile”: “”,
“ExtId”: “100”,
“PartyList”: {
“Count”: 3,
“List”: [{ “Value”: “部门a” }
,{ “Value”: “部门B/部门b” }
,{“Value”: “部门c” }
]
}
}
3.3.2 同步成员帐号资料
接口说明：
1、URL：openapi/user/sync
2、格式：JSON
3、HTTP 请求方式：GET/POST
4、输入参数说明：
参数名称类型描述
Action string 1=DEL, 2=ADD, 3=MOD
Alias string 帐号名，帐号名为邮箱格式
Name string 姓名
Gender string 性别：1=男，2=女
Position string 职位
Tel string 联系电话
Mobile string 手机
ExtId string 编号
Password string 密码
Md5 string 是否为Md5 密码，0=明文密码，1=Md5 密
码，
PartyPath string 所属部门
1、传部门路径，用’/’分隔
2、根部门不需要传。如果空，则为根部门。
部门是已存在的
3、如果是多个部门，传多个PartyPath
Slave string 别名列表
- 如果多个别名，传多个Slave
- Slave 上限为5 个
- Slave 为邮箱格式
OpenType string 0=不设置状态，1=启用帐号，2=禁用帐号
5、请求示例：
POST http://openapi.exmail.qq.com:12211/openapi/user/sync HTTP /1.1
Host: openapi.exmail.qq.com
Authorization: Bearer
GHUSH-4qIXPScxa_OY0CbPS31W1OM24L_Ys9FCc7LtJyxjHD5OZafLh3Y8gM7gzDtp-GdQEY4d
wFXk2qgnkwJA
Content-Length: 19
[email protected][email protected]
m
6、返回参数说明：
返回data 为空。通过返回状态码，判断是否调用成功。
3.3.3 获取某个版本号后的用户更新列表
接口说明：
1、URL：openapi/user/list
2、格式：JSON
3、HTTP 请求方式：GET/POST
4、输入参数说明：
参数名称类型描述
Ver string 版本号；初始=0 表示获取全
部帐号；如指定版本号，则
取该版本号之后的变更记录
5、请求示例：
POST http://openapi.exmail.qq.com:12211/openapi/user/list HTTP /1.1
Host: openapi.exmail.qq.com
Authorization: Bearer
GHUSH-4qIXPScxa_OY0CbPS31W1OM24L_Ys9FCc7LtJyxjHD5OZafLh3Y8gM7gzDtp-GdQEY4d
wFXk2qgnkwJA
Content-Length: 17
Ver=1386593148546
6、返回参数说明：
参数名称描述
Ver 最新版本号；初始=0 表示获取全部帐号
Count 成员个数
List 成员帐号列表
字段含义
Action 更新动作类型，1=Add, 2=Edit,
3=Del
Alias 帐号名
7、正确返回示例：
{
“Ver”: 1346674693912,
“Count”: 1,
“List”: [
{
“Action”: 3,
“Alias”: "[email protected]",
}
]
}
3.3.4 获取未读邮件数
接口说明：
1、URL：openapi/mail/newcount
2、格式：JSON
3、HTTP 请求方式：GET/POST
4、输入参数说明：
参数名称类型描述
Alias string 帐号名
5、请求示例：
POST http://openapi.exmail.qq.com:12211/openapi/mail/newcount HTTP /1.1
Host: openapi.exmail.qq.com
Authorization: Bearer
GHUSH-4qIXPScxa_OY0CbPS31W1OM24L_Ys9FCc7LtJyxjHD5OZafLh3Y8gM7gzDtp-GdQEY4d
wFXk2qgnkwJA
Content-Length: 19
[email protected]
6、返回参数说明：
参数名称描述
Alias 姓名
NewCount 新邮件数
7、正确返回示例：
{
“Alias”: "[email protected]",
"NewCount ": 15,
}
3.3.5 同步部门
接口说明：
1、URL：openapi/party/sync
2、格式：JSON
3、HTTP 请求方式：GET/POST
4、输入参数说明：
参数名称类型描述
Action string 更新动作类型，1=DEL, 2=ADD, 3=MOD
SrcPath string 源部门（注：部门用’/’ 分隔根部门不用加部门最多5 级，单个部门字符不超过64 个字符）
DstPath string 目标部门
注：
1）如果DEL/ADD，则只需要传DstPath
2）如果MOD，需要将SrcPath，和DstPath 传过来
5、请求示例：
请求示例：
POST http://openapi.exmail.qq.com:12211/openapi/user/list HTTP /1.1
Host: openapi.exmail.qq.com
Authorization: Bearer
GHUSH-4qIXPScxa_OY0CbPS31W1OM24L_Ys9FCc7LtJyxjHD5OZafLh3Y8gM7gzDtp-GdQEY4d
wFXk2qgnkwJA
Content-Length: 19
action=3&dstpath=%e9%83%a8%e9%97%a8A%2f%e5%ad%90%e9%83%a8%e9%97%a8a
6、返回参数说明：
参数名称描述
Count 部门总数
List 部门列表
字段含义
Value 子部门名称
注：返回的子部门不进行迭代遍历，只是最的一层子部门列表。
7、正确返回示例：
{
“Count”: 3,
“List”: [
{ “Value”: “部门a” }
,{ “Value”: “部门B” }
,{“Value”: “部门c” }
]
}
3.3.6 获取子部门列表
1、URL：openapi/party/list
2、格式：JSON
3、HTTP 请求方式：GET/POST
4、输入参数说明：
参数名称类型描述
PartyPath string 查看的父亲部门路径。如果看根部门，置为空。
5、请求示例：
POST http://openapi.exmail.qq.com:12211/openapi/party/list HTTP /1.1
Host: openapi.exmail.qq.com
Authorization: Bearer
GHUSH-4qIXPScxa_OY0CbPS31W1OM24L_Ys9FCc7LtJyxjHD5OZafLh3Y8gM7gzDtp-GdQEY4d
wFXk2qgnkwJA
Content-Length: 10
partypath=
6、返回参数说明：
参数名称描述
Count 部门总数
List 部门列表
字段含义
Value 子部门名称
注：返回的子部门不进行迭代遍历，只是最
近的一层子部门列表。
7、正确返回示例：
{
“Count”: 3,
“List”: [
{ “Value”: “部门a” }
,{ “Value”: “部门B” }
,{“Value”: “部门c” }
]
}
3.3.7 获取部门下成员列表
接口说明：
1、URL：openapi/partyuser/list
2、格式：JSON
3、HTTP 请求方式：GET/POS
4、输入参数说明：
参数名称类型描述
PartyPath string 查看的父亲部门路径。如果
查看根部门，置为空。
5、请求示例：
POST http://openapi.exmail.qq.com:12211/openapi/partyuser/list HTTP /1.1
Host: openapi.exmail.qq.com
Authorization: Bearer jIFA9ju6v5XP
Content-Length: 10
partypath=
6、返回参数说明：
参数名称描述
Count 部门总数
List 部门列表
字段含义
Value 帐号名称
7、正确返回示例：
{
“Count”: 1,
“List”: [
{ “Value”: "[email protected]" }
]
}
3.3.8 检查邮件帐号是否可用
接口说明：
1、URL：openapi/user/check
2、格式：JSON
3、HTTP 请求方式：GET/POST
4、输入参数说明：
参数名称类型描述
email string 邮件帐号(如果多个需要检查的邮件帐号，传多个email，email 上限为20 个)
5、请求示例：
POST http://openapi.exmail.qq.com:12211/openapi/user/check HTTP /1.1
Host: openapi.exmail.qq.com
Authorization: Bearer jIFA9ju6v5XP
Content-Length: 10
[email protected][email protected]
6、返回参数说明：
参数名称描述
Count 列表总数
List 帐号类型列表
字段含义
Email 帐号名称
Type 帐号类型。-1：帐号名无效，0：
帐号名没被占用，1：主帐号名，
2：别名帐号，3：邮件群组帐
号。
7、正确返回示例：
{
“Count”: 2,
“List”: [
{ “Email”: " [email protected] ", “Type”: 1 },
{ “Email”: " [email protected] ", “Type”: 0 }
]
}
3.3.9 添加邮件群组
接口说明：
1、URL：openapi/group/add
2、格式：JSON
3、HTTP 请求方式：GET/POST
4、输入参数说明：
参数名称类型描述
group_name string 群组名称
group_admin string 群组管理者（需要使用一个域中不存在的
邮箱地址）
status string 群组状态（分为4 类all，inner，group，
list）
members List 成员账号
字段含义
members 成员账号
5、请求示例：
POST http://openapi.exmail.qq.com:12211/openapi/group/add HTTP /1.1
Host: openapi.exmail.qq.com
Authorization: Bearer jIFA9ju6v5XP
Content-Length: 10
[email protected][email protected]
6、返回参数说明：
返回参数为空，并通过返回码判断函数执行是否成功。
3.3.10 删除邮件群组
接口说明：
1、URL：openapi/group/delete
2、格式：JSON
3、HTTP 请求方式：GET/POST
4、输入参数说明：
参数名称类型描述
group_alias string 群组管理员（一个域中不存在的邮箱地
址）
5、请求示例：
POST http://openapi.exmail.qq.com:12211/openapi/group/delete HTTP /1.1
Host: openapi.exmail.qq.com
Authorization: Bearer jIFA9ju6v5XP
Content-Length: 10
[email protected]
6、返回参数说明：
返回参数为空，并通过返回码判断函数执行是否成功。
3.3.121 添加邮件群组成员
接口说明：
1、URL：openapi/group/addmember
2、格式：JSON
3、HTTP 请求方式：GET/POST
4、输入参数说明：
参数名称类型描述
group_alias string 群组管理者（需要使用一个域中不存在的
邮箱地址）
members string 群组下的成员
5、请求示例：
POST http://openapi.exmail.qq.com:12211/openapi/group/addmember HTTP /1.1
Host: openapi.exmail.qq.com
Authorization: Bearer jIFA9ju6v5XP
Content-Length: 10
[email protected][email protected]
6、返回参数说明：
返回参数为空，并通过返回码判断函数执行是否成功。
3.3.12 删除邮件群组成员
接口说明：
7、URL：openapi/group/deletemember
8、格式：JSON
9、HTTP 请求方式：GET/POST
10、输入参数说明：
参数名称类型描述
group_alias string 群组管理者（需要使用一个域中不存在的
邮箱地址）
members string 群组下的成员
11、请求示例：
POST http://openapi.exmail.qq.com:12211/openapi/group/deletemember HTTP /1.1
Host: openapi.exmail.qq.com
Authorization: Bearer jIFA9ju6v5XP
Content-Length: 10
[email protected][email protected]
12、返回参数说明：
返回参数为空，并通过返回码判断函数执行是否成功。
四、附录：名词解释
4.1 长连接/短连接
长连接指建立SOCKET 连接后不管是否使用都保持连接；
短连接指建立SOCKET 连接后发送后接收完数据后马上断开连接。