php 腾讯企业邮箱接口,帮助中心 腾讯企业邮箱OpenApi协议

欢迎你，开发者

腾讯企业邮开放平台旨在为企业拓展、定制邮箱的功能。我们为开发者提供了五大开放接口：通讯录管理、新邮件提醒、单点登录、系统日志、功能设置。希望帮助企业提升开发效率、降低开发成本和难度，从而提升生产和管理之间的协作效率。

企业开发流程如下：

2.开发对接相关接口：开发测试应用，对接企业邮接口

一、开始开发

1.1主动调用：

主动调用是最基本的连接模式，当你的应用调用企业邮时，需使用HTTPS协议、Json数据格式、UTF8编码，访问域名为https://api.exmail.qq.com，数据包不需要加密。

在每次主动调用企业邮接口时需要带上AccessToken参数。AccessToken参数由CorpID和CorpSecret换取。

CorpID是企业邮的标识，每个企业邮拥有一个唯一的CorpID；

当企业应用调用企业邮接口时，企业邮后台根据此次访问的AccessToken，校验访问的合法性。

1.1.1基础频率

每企业调用单个cgi/api不可超过500次/分，15000次/小时

企业每ip调用接口不可超过10000次/分，300000次/小时

1.1.2获取ACCESS_TOKEN

HTTPS请求方式：GET

参数说明

参数

必须

说明

corpid

是

企业id

corpsecret

是

应用的凭证密钥

权限说明

每个应用有不同的secret，代表了对应用的不同权限

返回结果

{

"access_token": "accesstoken000001",

"expires_in": 7200

}

出错返回示例

{

"errcode":

40001,

"errmsg":

"invalid credential"

}

1.2回调模式：

在回调模式下，企业可以接收企业邮下发的数据。接收的信息使用XML数据格式、UTF8编码，并以AES方式加密。

企业邮的部分应用有自己的回调模式开关。在管理端开启并设置好相关参数后，此应用的回调模式才生效。

针对加解密的处理，企业邮提供了各种语言的库，企业可以在附录中下载。

1.2.1开启应用的回调模式

当你开启应用的回调模式时，企业邮会要求你填写应用的URL、Token、EncodingAESKey三个参数。

URL是企业应用接收企业邮推送请求的访问协议和地址，支持http或https协议。

Token可由企业任意填写，用于生成签名。

EncodingAESKey用于消息体的加密，是AES密钥的Base64编码。

验证URL、Token以及加密的详细处理请参考后续“接收消息时的加解密处理”的章节。

当你提交以上信息时，企业邮将发送GET请求到填写的URL上，GET请求携带四个参数，企业在获取时需要做urldecode处理，否则会验证不成功。

参数

描述

是否必带

msg_signature

企业邮加密签名，msg_signature结合了企业填写的token、请求中的timestamp、nonce参数、加密的消息体

是

timestamp

时间戳

是

nonce

随机数

是

echostr

加密的随机字符串，以msg_encrypt格式提供。需要解密并返回echostr明文，解密后有random、msg_len、msg、CorpID四个字段，其中msg即为echostr明文

首次校验时必带

企业通过参数msg_signature对请求进行校验，如果确认此次GET请求来自企业邮，那么企业应该对echostr参数解密并原样返回echostr明文(不能加引号，不能带bom头，不能带换行符)，则接入验证生效，回调模式才能开启。

后续回调企业时都会在请求URL中带上以上参数(echostr除外)，校验方式与首次验证URL一致。

使用回调模式

企业邮在回调企业URL时，会对消息体本身做AES加密，以XML格式POST到企业应用的URL上。

企业邮服务器在五秒内收不到响应会断掉连接，并且重新发起请求，总共重试三次。如果在调试中，发现成员无法收到响应的消息，可以检查是否消息处理超时。

当接收成功后，http头部返回200表示接收ok，其他错误码一律当做失败并发起重试 关于重试的消息排重，有MailID的消息推荐使用MailID排重 或者UserID + Time排重。

假设企业回调URL为http://api.3dept.com。

请求说明：

1、msg_encrypt为经过加密的密文

2、AppID为应用id，每个应用都有唯一的id

3、CorpID为企业邮的CorpID

企业需要对msg_signature进行校验，并解密msg_encrypt，得出msg的原文。

二、通讯录管理

2.1 管理部门

2.1.1创建部门

请求说明

HTTPS请求方式：POST

请求地址：https://api.exmail.qq.com/cgi-bin/department/create?access_token=ACCESS_TOKEN

请求包结构体为：

{

"name":

"广州研发中心",

"parentid": 1,

"order": 1

}

参数说明

参数

必须

说明

access_token

是

调用接口凭证

name

是

部门名称。长度限制为1~64个字节，字符不能包括\:*?"<>｜

parentid

是

父部门id。id为1可表示根部门

order

否

在父部门中的次序值。order值小的排序靠前。

权限说明

系统应用须拥有父部门的管理权限。

返回结果

{

"errcode":

0,

"errmsg":

"created",

"id": 2

}

参数

说明

errcode

返回码

errmsg

对返回码的文本描述内容

id

创建的部门id。id为64位整型数

2.1.2更新部门

请求说明：

HTTPS请求方式：POST

请求地址：https://api.exmail.qq.com/cgi-bin/department/update?access_token=ACCESS_TOKEN

请求包结构体为(如果非必须的字段未指定，则不更新该字段之前的设置值):

{

"id": 2,

"name":

"广州研发中心",

"parentid": 1,

"order": 1

}

·         参数说明：

参数

必须

说明

access_token

是

调用接口凭证

id

是

部门id

name

否

更新的部门名称。长度限制为1~64个字节，字符不能包括\:*?"<>｜。修改部门名称时指定该参数

parentid

否

父部门id。id为1可表示根部门

order

否

在父部门中的次序值。order值小的排序靠前。

权限说明

系统应用须拥有指定部门的管理权限。

返回结果

{

"errcode":

0,

"errmsg":

"updated"

}

参数

说明

errcode

返回码

errmsg

对返回码的文本描述内容

2.1.3删除部门

请求说明：

HTTPS请求方式：GET

请求地址：https://api.exmail.qq.com/cgi-bin/department/delete?access_token=ACCESS_TOKEN&id=ID

参数说明：

参数

必须

说明

access_token

是

调用接口凭证

id

是

部门id。(注：不能删除根部门；不能删除含有子部门、成员的部门)

权限说明

系统应用须拥有指定部门的管理权限。

返回结果

{

"errcode":

0,

"errmsg":

"deleted"

}

参数

说明

errcode

返回码

errmsg

对返回码的文本描述内容

2.1.4获取部门列表

请求说明：

HTTPS请求方式：GET

请求地址： https://api.exmail.qq.com/cgi-bin/department/list?access_token=ACCESS_TOKEN&id=ID

·

参数说明：

参数

必须

说明

access_token

是

调用接口凭证

id

否

部门id。获取指定部门及其下的子部门。id为1时可获取根部门下的子部门。

权限说明

系统应用须拥有指定部门的查看权限。

返回结果

{

"errcode":

0,

"errmsg":

"ok",

"department": [{

"id": 2,

"name": "广州研发中心",

"parentid": 1,

"order": 10

},{

"id": 3

"name": "邮箱产品部",

"parentid": 2,

"order": 40

}]

}

参数

说明

errcode

返回码

errmsg

对返回码的文本描述内容

department

部门列表数据。以部门的order字段从小到大排列

id

部门id

name

部门名称

parentid

父部门id。

order

在父部门中的次序值。order值小的排序靠前

2.1.5查找部门

请求说明：

HTTPS请求方式：POST

请求地址：https://api.exmail.qq.com/cgi-bin/department/search?access_token=ACCESS_TOKEN

请求包结构体为：

{

"name":

"邮箱产品部",

"fuzzy":

0,

}

参数说明：

参数

必须

说明

access_token

是

调用接口凭证

name

否

查找的部门名字，必须合法

fuzzy

否

1/0：是否模糊匹配

权限说明

系统应用须拥有指定部门的查看权限。

返回结果

{

"errcode":

0,

"errmsg":

"ok",

"department": [

{

"id": 3

"name": "邮箱产品部",

"parentid":

2,

"order": 40,

"path":"广州研发中心/邮箱产品部"

},

{

"id": 10

"name": "邮箱产品部",

"parentid": 6,

"order": 40,

"path":"深圳研发中心/邮箱产品部"

}

]

}

参数

说明

errcode

返回码

errmsg

对返回码的文本描述内容

department

部门列表数据。以部门的order字段从小到大排列

id

部门id

name

部门名称

parentid

父部门id。根部门为0

order

在父部门中的次序值。order值小的排序靠前。

path

部门路径，部门用’/ ’作分割符

2.2 管理成员

2.2.1创建成员

请求说明：

HTTPS请求方式：POST

请求地址： https://api.exmail.qq.com/cgi-bin/user/create?access_token=ACCESS_TOKEN

请求包结构体为：

{

"userid": " zhangsan@gzdev.com

",

"name": "张三",

"department": [1, 2],

"position": "产品经理",

"mobile": "15913215XXX",

"tel": "123456",

"extid": "01",

"gender": "1",

"slaves":

[zhangsan@gz.com, zhangsan@bjdev.com],

"password":"******",

"cpwd_login":0

}

参数说明：

参数

必须

说明

access_token

是

调用接口凭证

userid

是

成员UserID。企业邮帐号名，邮箱格式

name

是

成员名称。长度为1~64个字节

department

是

成员所属部门id列表，不超过20个

position

否

职位信息。长度为0~64个字节