腾讯企业邮箱OpenApi调用说明
筆者最近在調(diào)用騰訊企業(yè)郵箱的接口,但因?yàn)轫?xiàng)目使用的是2016年的老接口,不是新接口(https://exmail.qq.com/qy_mng_logic/doc#10001)
因此找到了之前的老接口文檔供自己和大家參考。
一、開放協(xié)議介紹
- 1.1 功能簡介
騰訊企業(yè)郵箱開放協(xié)議,包括面向第三方合作應(yīng)用和面向企業(yè)郵用戶兩類。其中,面向
企業(yè)郵用戶的開放協(xié)議,將提供給企業(yè)郵用戶豐富的應(yīng)用接口,用戶可以根據(jù)這些接口定制己統(tǒng)一的企業(yè)解決方案。
通過協(xié)議接口,企業(yè)用戶可以實(shí)現(xiàn):
可以從公司OA 系統(tǒng)、網(wǎng)站一鍵進(jìn)入企業(yè)郵箱,免去登錄過程。
新郵件將即時(shí)在OA 等辦公系統(tǒng)提醒你。
數(shù)據(jù)同步可以幫助你同步部門成員信息,你還可以創(chuàng)建、刪除、修改帳號(hào),同步部門信息等。
-
1.2 協(xié)議格式
協(xié)議采用HTTP+JSON 格式,請求采用GET/POST 方式。 -
1.3 安全機(jī)制
- 1.4 協(xié)議編碼
均用UTF-8 編碼。
二、接入流程
接入騰訊企業(yè)郵開放接口的全流程圖如下:
- 2.1 管理端申請
從鏈接http://exmail.qq.com 進(jìn)入,使用管理員賬號(hào)登錄進(jìn)入管理頁面,打開“工具箱->開放議”,點(diǎn)擊“立即申請”。
- 2.2 獲取接口key
接口key,是作為下一步OAuth 驗(yàn)證授權(quán)傳遞的參數(shù),需要查看明文。
(1)點(diǎn)擊“查看明文”:
(2)輸入管理員密碼,點(diǎn)擊“確定”
(3)可查看接口key
截圖中的接口key 為563a8c6a89d2368194c1c7889c508b34
- 2.3 OAuth 驗(yàn)證授權(quán)
接口說明:
目前,騰訊企業(yè)郵箱采用OAuth2.0 協(xié)議對第三方進(jìn)行授權(quán),關(guān)于OAuth2.0 的詳細(xì)介紹,請考OAuth 協(xié)議標(biāo)準(zhǔn)。
客戶端通過長連接維持在線狀態(tài),服務(wù)端通過檢查用戶的在線狀態(tài),實(shí)時(shí)推送消息;同時(shí)客端根據(jù)同一個(gè)連接,獲取請求數(shù)據(jù)。
調(diào)用的方式有兩種方式:
POST 方式:在POST 請求加上access_token;
GET 或者其他方式:在HTTP HEAD 加上Authorization,將client_id 和client_secret 以
BASE64 加密方式加密,即base64(client_id: client_secret),將密文發(fā)送到請求信息中。
1、URL:https://exmail.qq.com/cgi-bin/token
2、格式:JSON
3、HTTP 請求方式:GET/POST
4、輸入?yún)?shù)說明:
參數(shù)名稱類型描述
client_id string 當(dāng)前管理員帳號(hào)
client_secret string 接口key
5、請求示例:
請求的參數(shù):
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
或者:
請求的參數(shù):
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、返回參數(shù)說明:
參數(shù)名稱描述
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 調(diào)用接口Api(客戶端請求)
經(jīng)過OAuth 授權(quán)驗(yàn)證后,獲取到access_token,開發(fā)者可以根據(jù)實(shí)現(xiàn)功能的需要去選擇調(diào)用API。以下章節(jié)將列出接口API 的功能和調(diào)用方式。
三、調(diào)用接口API 說明
接口API 能實(shí)現(xiàn)的功能有如下三個(gè):
(1)單點(diǎn)登錄:
可以從公司OA 系統(tǒng)、網(wǎng)站一鍵進(jìn)入企業(yè)郵箱,免去登錄過程。
(2)新郵件提醒:
新郵件將即時(shí)在OA 等辦公系統(tǒng)提醒你。
(3)同步
數(shù)據(jù)同步可以幫助你同步部門成員信息,你還可以創(chuàng)建、刪除、修改帳號(hào),同步部門信息等。
- 3.1 單點(diǎn)登錄
可以從公司OA 系統(tǒng)、網(wǎng)站一鍵進(jìn)入企業(yè)郵箱,免去登錄過程。接入流程圖如下所示:
3.1.1 獲取Authkey
接口說明:
1、URL:openapi/mail/authkey
2、格式:JSON
3、HTTP 請求方式:GET/POST
4、輸入?yún)?shù)說明:
參數(shù)名稱類型描述
Alias string 帳號(hào)名
5、請求示例:
請求參數(shù):bob@gzdev.com
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
alias=test0507@gzservice.com
6、返回參數(shù)說明:
參數(shù)名稱描述
AuthKey 登陸/讀信驗(yàn)證Key
7、正確返回示例:
{
“AuthKey”:
"077FFF01B4D6A28A07A21682C3C0D4FE04221261CE2E3FAFA9E8432937DCF57290EA36BAD
05815167251FF690134EDE4F40055B1B7B68C1D "
}
3.1.2 一鍵登錄
接口說明:
1、URL:
2、格式:JSON
3、HTTP 請求方式:GET/POST
4、輸入?yún)?shù)說明:
參數(shù)名稱類型描述
ticket string 調(diào)用“獲取Authkey”獲
取的Authkey
agent string 管理員帳號(hào)
5、請求示例:
https://exmail.qq.com/cgi-bin/login?fun=bizopenssologin&method=bizauth&agent=&user=&ticket=
6、返回參數(shù)說明:
參數(shù)名稱描述
mailid 服務(wù)器推送新郵件時(shí)的mailid 字段
7、正確返回示例
- 3.2 郵件提醒
新郵件將即時(shí)在OA 等辦公系統(tǒng)提醒你。接入的流程圖如下:
3.2.1 客戶端維持長連接
調(diào)用說明:
調(diào)用此api 是用于維持客戶端與服務(wù)器的長連接。
1、URL:openapi/listen
2、格式:JSON
3、HTTP 請求方式:GET/POST
4、輸入?yún)?shù)說明:
參數(shù)名稱類型描述
Ver string 本地維護(hù)的最新版本號(hào)
5、請求示例(初始版本號(hào)設(shè)置為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、返回參數(shù)說明:
如果當(dāng)前客戶端長連接在線,會(huì)返回參數(shù)“Ret”,當(dāng)服務(wù)端檢查到服務(wù)器版本號(hào)數(shù)據(jù)變更時(shí),發(fā)最新版本號(hào)“ver”。
參數(shù)名稱描述
Ret 返回值
7、正確返回示例:
{
“Ret”: 0
}
3.2.2 下發(fā)數(shù)據(jù)
如果當(dāng)前客戶端長連接在線,當(dāng)服務(wù)端檢查到數(shù)據(jù)變更時(shí),將會(huì)下發(fā)數(shù)據(jù):版本號(hào)更新;新
郵件提醒;實(shí)時(shí)更新未讀郵件數(shù)。
(1)版本號(hào)更新
1、下發(fā)字段:
參數(shù)名稱類型描述
Ver string 服務(wù)器最新版本號(hào)
2、下發(fā)示例:
{
“Ver”: “1364460338051”,
}
(2)新郵件提醒
1、下發(fā)字段:
參數(shù)名稱描述
UserName 帳號(hào)名
MailId 郵件Id
Sender 發(fā)件人
Receiver 收件人
Subject 標(biāo)題
Summary 摘要
NewCount 新郵件數(shù)
2、下發(fā)示例:
{
“UserName”: "bob@gzdev.com",
“MailId”: “ZC4028-FPiX_oOG5HUh4XorwyhAY33”,
“Sender”: ““Test” test@gzdev.com”,
“Receiver”: "bob@gzdev.com",
“Subject”: “TestMail”,
“Summary”: "TestMail Content ",
“NewCount”: 549
}
(3)實(shí)時(shí)更新未讀郵件數(shù)
1、下發(fā)字段:
參數(shù)名稱描述
UserName 帳號(hào)
NewCount 未讀郵件數(shù)
2、下發(fā)示例:
{
" UserName": "bob@gzdev.com",
" NewCount ": 550,
}
- 3.3 數(shù)據(jù)同步
數(shù)據(jù)同步可以幫助你同步部門成員信息,你還可以創(chuàng)建、刪除、修改帳號(hào),同步部門信息等。
接入的流程圖如下:
3.3.1 獲取成員資料
接口說明:
1、URL:openapi/user/get
2、格式:JSON
3、HTTP 請求方式:GET/POST
4、輸入?yún)?shù)說明:
參數(shù)名稱類型描述
Alias string 當(dāng)前管理員帳號(hào)
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= test2@gzservice.com
6、返回參數(shù)說明:
參數(shù)名稱描述
Alias 帳號(hào)名
Name 姓名
Gender 性別:0=未設(shè)置,1=男,2=女
SlaveList 別名列表,用逗號(hào)分隔
Position 職位
Tel 聯(lián)系電話
Mobile 手機(jī)
ExtId 編號(hào)
PartyList 部門列表,部門的根結(jié)點(diǎn)不包括在路徑里面。比如部門所屬:騰
訊/廣州研發(fā)中心/企業(yè)郵箱,Value 為:廣州研發(fā)中心/企業(yè)郵箱
OpenType 成員狀態(tài):1=啟用,2=禁用
7、正確返回示例:
{
“Alias”: " test2@gzservice.com",
“Name”: “鮑勃”,
“Gender”: 1,
“SlaveList”: "bb@gzdev.com,bo@gzdev.com",
“Position”: “工程師”,
“Tel”: “62394”,
“Mobile”: “”,
“ExtId”: “100”,
“PartyList”: {
“Count”: 3,
“List”: [{ “Value”: “部門a” }
,{ “Value”: “部門B/部門b” }
,{“Value”: “部門c” }
]
}
}
3.3.2 同步成員帳號(hào)資料
接口說明:
1、URL:openapi/user/sync
2、格式:JSON
3、HTTP 請求方式:GET/POST
4、輸入?yún)?shù)說明:
參數(shù)名稱類型描述
Action string 1=DEL, 2=ADD, 3=MOD
Alias string 帳號(hào)名,帳號(hào)名為郵箱格式
Name string 姓名
Gender string 性別:1=男,2=女
Position string 職位
Tel string 聯(lián)系電話
Mobile string 手機(jī)
ExtId string 編號(hào)
Password string 密碼
Md5 string 是否為Md5 密碼,0=明文密碼,1=Md5 密
碼,
PartyPath string 所屬部門
1、傳部門路徑,用’/’分隔
2、根部門不需要傳。如果空,則為根部門。
部門是已存在的
3、如果是多個(gè)部門,傳多個(gè)PartyPath
Slave string 別名列表
OpenType string 0=不設(shè)置狀態(tài),1=啟用帳號(hào),2=禁用帳號(hào)
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
action=3&alias=bob@gzdev.com&name=BOB&gender=1&position=engineer&slave=test@gzdev.co
m
6、返回參數(shù)說明:
返回data 為空。通過返回狀態(tài)碼,判斷是否調(diào)用成功。
3.3.3 獲取某個(gè)版本號(hào)后的用戶更新列表
接口說明:
1、URL:openapi/user/list
2、格式:JSON
3、HTTP 請求方式:GET/POST
4、輸入?yún)?shù)說明:
參數(shù)名稱類型描述
Ver string 版本號(hào);初始=0 表示獲取全
部帳號(hào);如指定版本號(hào),則
取該版本號(hào)之后的變更記錄
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、返回參數(shù)說明:
參數(shù)名稱描述
Ver 最新版本號(hào);初始=0 表示獲取全部帳號(hào)
Count 成員個(gè)數(shù)
List 成員帳號(hào)列表
字段含義
Action 更新動(dòng)作類型,1=Add, 2=Edit,
3=Del
Alias 帳號(hào)名
7、正確返回示例:
{
“Ver”: 1346674693912,
“Count”: 1,
“List”: [
{
“Action”: 3,
“Alias”: "test2@gzservice.com",
}
]
}
3.3.4 獲取未讀郵件數(shù)
接口說明:
1、URL:openapi/mail/newcount
2、格式:JSON
3、HTTP 請求方式:GET/POST
4、輸入?yún)?shù)說明:
參數(shù)名稱類型描述
Alias string 帳號(hào)名
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
alias=test0507@gzservice.com
6、返回參數(shù)說明:
參數(shù)名稱描述
Alias 姓名
NewCount 新郵件數(shù)
7、正確返回示例:
{
“Alias”: "test0507@gzservice.com",
"NewCount ": 15,
}
3.3.5 同步部門
接口說明:
1、URL:openapi/party/sync
2、格式:JSON
3、HTTP 請求方式:GET/POST
4、輸入?yún)?shù)說明:
參數(shù)名稱類型描述
Action string 更新動(dòng)作類型,1=DEL, 2=ADD, 3=MOD
SrcPath string 源部門(注:部門用’/’ 分隔根部門不用加部門最多5 級(jí),單個(gè)部門字符不超過64 個(gè)字符)
DstPath string 目標(biāo)部門
注:
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、返回參數(shù)說明:
參數(shù)名稱描述
Count 部門總數(shù)
List 部門列表
字段含義
Value 子部門名稱
注:返回的子部門不進(jìn)行迭代遍歷,只是最的一層子部門列表。
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、輸入?yún)?shù)說明:
參數(shù)名稱類型描述
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、返回參數(shù)說明:
參數(shù)名稱描述
Count 部門總數(shù)
List 部門列表
字段含義
Value 子部門名稱
注:返回的子部門不進(jìn)行迭代遍歷,只是最
近的一層子部門列表。
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、輸入?yún)?shù)說明:
參數(shù)名稱類型描述
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、返回參數(shù)說明:
參數(shù)名稱描述
Count 部門總數(shù)
List 部門列表
字段含義
Value 帳號(hào)名稱
7、正確返回示例:
{
“Count”: 1,
“List”: [
{ “Value”: "bob@gzdev.com" }
]
}
3.3.8 檢查郵件帳號(hào)是否可用
接口說明:
1、URL:openapi/user/check
2、格式:JSON
3、HTTP 請求方式:GET/POST
4、輸入?yún)?shù)說明:
參數(shù)名稱類型描述
email string 郵件帳號(hào)(如果多個(gè)需要檢查的郵件帳號(hào),傳多個(gè)email,email 上限為20 個(gè))
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=test@gzdev.com&email=2013@gzdev.com
6、返回參數(shù)說明:
參數(shù)名稱描述
Count 列表總數(shù)
List 帳號(hào)類型列表
字段含義
Email 帳號(hào)名稱
Type 帳號(hào)類型。-1:帳號(hào)名無效,0:
帳號(hào)名沒被占用,1:主帳號(hào)名,
2:別名帳號(hào),3:郵件群組帳
號(hào)。
7、正確返回示例:
{
“Count”: 2,
“List”: [
{ “Email”: " test@gzdev.com ", “Type”: 1 },
{ “Email”: " 2013@gzdev.com ", “Type”: 0 }
]
}
3.3.9 添加郵件群組
接口說明:
1、URL:openapi/group/add
2、格式:JSON
3、HTTP 請求方式:GET/POST
4、輸入?yún)?shù)說明:
參數(shù)名稱類型描述
group_name string 群組名稱
group_admin string 群組管理者(需要使用一個(gè)域中不存在的
郵箱地址)
status string 群組狀態(tài)(分為4 類all,inner,group,
list)
members List 成員賬號(hào)
字段含義
members 成員賬號(hào)
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
group_name=test&group_admin=test@gzdev.com&status=all&members=test1@gzdev.com
6、返回參數(shù)說明:
返回參數(shù)為空,并通過返回碼判斷函數(shù)執(zhí)行是否成功。
3.3.10 刪除郵件群組
接口說明:
1、URL:openapi/group/delete
2、格式:JSON
3、HTTP 請求方式:GET/POST
4、輸入?yún)?shù)說明:
參數(shù)名稱類型描述
group_alias string 群組管理員(一個(gè)域中不存在的郵箱地
址)
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
group_alias=test@gzdev.com
6、返回參數(shù)說明:
返回參數(shù)為空,并通過返回碼判斷函數(shù)執(zhí)行是否成功。
3.3.121 添加郵件群組成員
接口說明:
1、URL:openapi/group/addmember
2、格式:JSON
3、HTTP 請求方式:GET/POST
4、輸入?yún)?shù)說明:
參數(shù)名稱類型描述
group_alias string 群組管理者(需要使用一個(gè)域中不存在的
郵箱地址)
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
group_alias=test@gzdev.com&members=test1@gzdev.com
6、返回參數(shù)說明:
返回參數(shù)為空,并通過返回碼判斷函數(shù)執(zhí)行是否成功。
3.3.12 刪除郵件群組成員
接口說明:
7、URL:openapi/group/deletemember
8、格式:JSON
9、HTTP 請求方式:GET/POST
10、輸入?yún)?shù)說明:
參數(shù)名稱類型描述
group_alias string 群組管理者(需要使用一個(gè)域中不存在的
郵箱地址)
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
group_alias=test@gzdev.com&members=test1@gzdev.com
12、返回參數(shù)說明:
返回參數(shù)為空,并通過返回碼判斷函數(shù)執(zhí)行是否成功。
四、附錄:名詞解釋
4.1 長連接/短連接
長連接指建立SOCKET 連接后不管是否使用都保持連接;
短連接指建立SOCKET 連接后發(fā)送后接收完數(shù)據(jù)后馬上斷開連接。
總結(jié)
以上是生活随笔為你收集整理的腾讯企业邮箱OpenApi调用说明的全部內(nèi)容,希望文章能夠幫你解決所遇到的問題。
- 上一篇: 【自动驾驶】【数据集】KITTI数据集简
- 下一篇: 零知识证明