歡迎你，開發(fā)者

騰訊企業(yè)郵開放平臺旨在為企業(yè)拓展、定制郵箱的功能。我們?yōu)殚_發(fā)者提供了五大開放接口：通訊錄管理、新郵件提醒、單點登錄、系統(tǒng)日志、功能設(shè)置。希望幫助企業(yè)提升開發(fā)效率、降低開發(fā)成本和難度，從而提升生產(chǎn)和管理之間的協(xié)作效率。

企業(yè)開發(fā)流程如下：

2.開發(fā)對接相關(guān)接口：開發(fā)測試應(yīng)用，對接企業(yè)郵接口

一、開始開發(fā)

1.1主動調(diào)用：

主動調(diào)用是最基本的連接模式，當(dāng)你的應(yīng)用調(diào)用企業(yè)郵時，需使用HTTPS協(xié)議、Json數(shù)據(jù)格式、UTF8編碼，訪問域名為https://api.exmail.qq.com，數(shù)據(jù)包不需要加密。

在每次主動調(diào)用企業(yè)郵接口時需要帶上AccessToken參數(shù)。AccessToken參數(shù)由CorpID和CorpSecret換取。

CorpID是企業(yè)郵的標(biāo)識，每個企業(yè)郵擁有一個唯一的CorpID；

當(dāng)企業(yè)應(yīng)用調(diào)用企業(yè)郵接口時，企業(yè)郵后臺根據(jù)此次訪問的AccessToken，校驗訪問的合法性。

1.1.1基礎(chǔ)頻率

每企業(yè)調(diào)用單個cgi/api不可超過500次/分，15000次/小時

企業(yè)每ip調(diào)用接口不可超過10000次/分，300000次/小時

1.1.2獲取ACCESS_TOKEN

HTTPS請求方式：GET

參數(shù)說明

參數(shù)

必須

說明

corpid

是

企業(yè)id

corpsecret

是

應(yīng)用的憑證密鑰

權(quán)限說明

每個應(yīng)用有不同的secret，代表了對應(yīng)用的不同權(quán)限

返回結(jié)果

{

"access_token": "accesstoken000001",

"expires_in": 7200

}

出錯返回示例

{

"errcode":

40001,

"errmsg":

"invalid credential"

}

1.2回調(diào)模式：

在回調(diào)模式下，企業(yè)可以接收企業(yè)郵下發(fā)的數(shù)據(jù)。接收的信息使用XML數(shù)據(jù)格式、UTF8編碼，并以AES方式加密。

企業(yè)郵的部分應(yīng)用有自己的回調(diào)模式開關(guān)。在管理端開啟并設(shè)置好相關(guān)參數(shù)后，此應(yīng)用的回調(diào)模式才生效。

針對加解密的處理，企業(yè)郵提供了各種語言的庫，企業(yè)可以在附錄中下載。

1.2.1開啟應(yīng)用的回調(diào)模式

當(dāng)你開啟應(yīng)用的回調(diào)模式時，企業(yè)郵會要求你填寫應(yīng)用的URL、Token、EncodingAESKey三個參數(shù)。

URL是企業(yè)應(yīng)用接收企業(yè)郵推送請求的訪問協(xié)議和地址，支持http或https協(xié)議。

Token可由企業(yè)任意填寫，用于生成簽名。

EncodingAESKey用于消息體的加密，是AES密鑰的Base64編碼。

驗證URL、Token以及加密的詳細(xì)處理請參考后續(xù)“接收消息時的加解密處理”的章節(jié)。

當(dāng)你提交以上信息時，企業(yè)郵將發(fā)送GET請求到填寫的URL上，GET請求攜帶四個參數(shù)，企業(yè)在獲取時需要做urldecode處理，否則會驗證不成功。

參數(shù)

描述

是否必帶

msg_signature

企業(yè)郵加密簽名，msg_signature結(jié)合了企業(yè)填寫的token、請求中的timestamp、nonce參數(shù)、加密的消息體

是

timestamp

時間戳

是

nonce

隨機(jī)數(shù)

是

echostr

加密的隨機(jī)字符串，以msg_encrypt格式提供。需要解密并返回echostr明文，解密后有random、msg_len、msg、CorpID四個字段，其中msg即為echostr明文

首次校驗時必帶

企業(yè)通過參數(shù)msg_signature對請求進(jìn)行校驗，如果確認(rèn)此次GET請求來自企業(yè)郵，那么企業(yè)應(yīng)該對echostr參數(shù)解密并原樣返回echostr明文(不能加引號，不能帶bom頭，不能帶換行符)，則接入驗證生效，回調(diào)模式才能開啟。

后續(xù)回調(diào)企業(yè)時都會在請求URL中帶上以上參數(shù)(echostr除外)，校驗方式與首次驗證URL一致。

使用回調(diào)模式

企業(yè)郵在回調(diào)企業(yè)URL時，會對消息體本身做AES加密，以XML格式POST到企業(yè)應(yīng)用的URL上。

企業(yè)郵服務(wù)器在五秒內(nèi)收不到響應(yīng)會斷掉連接，并且重新發(fā)起請求，總共重試三次。如果在調(diào)試中，發(fā)現(xiàn)成員無法收到響應(yīng)的消息，可以檢查是否消息處理超時。

當(dāng)接收成功后，http頭部返回200表示接收ok，其他錯誤碼一律當(dāng)做失敗并發(fā)起重試 關(guān)于重試的消息排重，有MailID的消息推薦使用MailID排重 或者UserID + Time排重。

假設(shè)企業(yè)回調(diào)URL為http://api.3dept.com。

請求說明：

1、msg_encrypt為經(jīng)過加密的密文

2、AppID為應(yīng)用id，每個應(yīng)用都有唯一的id

3、CorpID為企業(yè)郵的CorpID

企業(yè)需要對msg_signature進(jìn)行校驗，并解密msg_encrypt，得出msg的原文。

二、通訊錄管理

2.1 管理部門

2.1.1創(chuàng)建部門

請求說明

HTTPS請求方式：POST

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

請求包結(jié)構(gòu)體為：

{

"name":

"廣州研發(fā)中心",

"parentid": 1,

"order": 1

}

參數(shù)說明

參數(shù)

必須

說明

access_token

是

調(diào)用接口憑證

name

是

部門名稱。長度限制為1~64個字節(jié)，字符不能包括\:*?"<>｜

parentid

是

父部門id。id為1可表示根部門

order

否

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

權(quán)限說明

系統(tǒng)應(yīng)用須擁有父部門的管理權(quán)限。

返回結(jié)果

{

"errcode":

0,

"errmsg":

"created",

"id": 2

}

參數(shù)

說明

errcode

返回碼

errmsg

對返回碼的文本描述內(nèi)容

id

創(chuàng)建的部門id。id為64位整型數(shù)

2.1.2更新部門

請求說明：

HTTPS請求方式：POST

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

請求包結(jié)構(gòu)體為(如果非必須的字段未指定，則不更新該字段之前的設(shè)置值):

{

"id": 2,

"name":

"廣州研發(fā)中心",

"parentid": 1,

"order": 1

}

·???????? 參數(shù)說明：

參數(shù)

必須

說明

access_token

是

調(diào)用接口憑證

id

是

部門id

name

否

更新的部門名稱。長度限制為1~64個字節(jié)，字符不能包括\:*?"<>｜。修改部門名稱時指定該參數(shù)

parentid

否

父部門id。id為1可表示根部門

order

否

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

權(quán)限說明

系統(tǒng)應(yīng)用須擁有指定部門的管理權(quán)限。

返回結(jié)果

{

"errcode":

0,

"errmsg":

"updated"

}

參數(shù)

說明

errcode

返回碼

errmsg

對返回碼的文本描述內(nèi)容

2.1.3刪除部門

請求說明：

HTTPS請求方式：GET

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

參數(shù)說明：

參數(shù)

必須

說明

access_token

是

調(diào)用接口憑證

id

是

部門id。(注：不能刪除根部門；不能刪除含有子部門、成員的部門)

權(quán)限說明

系統(tǒng)應(yīng)用須擁有指定部門的管理權(quán)限。

返回結(jié)果

{

"errcode":

0,

"errmsg":

"deleted"

}

參數(shù)

說明

errcode

返回碼

errmsg

對返回碼的文本描述內(nèi)容

2.1.4獲取部門列表

請求說明：

HTTPS請求方式：GET

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

·

參數(shù)說明：

參數(shù)

必須

說明

access_token

是

調(diào)用接口憑證

id

否

部門id。獲取指定部門及其下的子部門。id為1時可獲取根部門下的子部門。

權(quán)限說明

系統(tǒng)應(yīng)用須擁有指定部門的查看權(quán)限。

返回結(jié)果

{

"errcode":

0,

"errmsg":

"ok",

"department": [{

"id": 2,

"name": "廣州研發(fā)中心",

"parentid": 1,

"order": 10

},{

"id": 3

"name": "郵箱產(chǎn)品部",

"parentid": 2,

"order": 40

}]

}

參數(shù)

說明

errcode

返回碼

errmsg

對返回碼的文本描述內(nèi)容

department

部門列表數(shù)據(jù)。以部門的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

請求包結(jié)構(gòu)體為：

{

"name":

"郵箱產(chǎn)品部",

"fuzzy":

0,

}

參數(shù)說明：

參數(shù)

必須

說明

access_token

是

調(diào)用接口憑證

name

否

查找的部門名字，必須合法

fuzzy

否

1/0：是否模糊匹配

權(quán)限說明

系統(tǒng)應(yīng)用須擁有指定部門的查看權(quán)限。

返回結(jié)果

{

"errcode":

0,

"errmsg":

"ok",

"department": [

{

"id": 3

"name": "郵箱產(chǎn)品部",

"parentid":

2,

"order": 40,

"path":"廣州研發(fā)中心/郵箱產(chǎn)品部"

},

{

"id": 10

"name": "郵箱產(chǎn)品部",

"parentid": 6,

"order": 40,

"path":"深圳研發(fā)中心/郵箱產(chǎn)品部"

}

]

}

參數(shù)

說明

errcode

返回碼

errmsg

對返回碼的文本描述內(nèi)容

department

部門列表數(shù)據(jù)。以部門的order字段從小到大排列

id

部門id

name

部門名稱

parentid

父部門id。根部門為0

order

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

path

部門路徑，部門用’/ ’作分割符

2.2 管理成員

2.2.1創(chuàng)建成員

請求說明：

HTTPS請求方式：POST

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

請求包結(jié)構(gòu)體為：

{

"userid": " zhangsan@gzdev.com

",

"name": "張三",

"department": [1, 2],

"position": "產(chǎn)品經(jīng)理",

"mobile": "15913215XXX",

"tel": "123456",

"extid": "01",

"gender": "1",

"slaves":

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

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

"cpwd_login":0

}

參數(shù)說明：

參數(shù)

必須

說明

access_token

是

調(diào)用接口憑證

userid

是

成員UserID。企業(yè)郵帳號名，郵箱格式

name

是

成員名稱。長度為1~64個字節(jié)

department

是

成員所屬部門id列表，不超過20個

position

否

職位信息。長度為0~64個字節(jié)

總結(jié)

以上是生活随笔為你收集整理的php 腾讯企业邮箱接口,帮助中心 腾讯企业邮箱OpenApi协议的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。