本文說明 Email Settings API 與 Gmail API 之間的主要差異。本指南可協助您將應用程式遷移至 Gmail API。
授權要求
與 Email Settings API 一樣,Gmail API 會使用 OAuth 2.0 通訊協定授權要求。兩者的主要差異在於,Gmail API 權限的範圍是個別使用者,而非整個網域。這表示即使授權網域管理員帳戶,也無法為網域中的其他使用者遷移郵件。您必須改用管理控制台中加入許可清單的標準服務帳戶,才能產生適當的驗證權杖。
Email Settings API 使用範圍:
https://apps-apis.google.com/a/feeds/emailsettings/2.0/
Gmail API 中的對等範圍如下:
https://www.googleapis.com/auth/gmail.settings.basic
https://www.googleapis.com/auth/gmail.settings.sharing
通訊協定變更
Email Settings API 使用 XML 型 GDATA 通訊協定。Gmail API 使用 JSON。由於設定主要是由鍵/值組合所組成,因此各版本之間的酬載在概念上十分相似。
標籤建立範例:
Email Settings API
POST https://apps-apis.google.com/a/feeds/emailsettings/2.0/{domain name}/{username}/label
<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
<apps:property name="label" value="status updates" />
</atom:entry>
Gmail API
POST https://www.googleapis.com/gmail/v1/users/{username}/labels
{
"name": "status updates"
}
請使用提供的用戶端程式庫,不要直接實作通訊協定。
管理標籤
如要在 Gmail API 中管理標籤,請使用 Labels 資源。
舊設定 | 新設定 | 附註 |
---|---|---|
labelId | id | |
標籤 | 名稱 | |
unreadCount | messagesUnread | |
顯示設定 | labelListVisibility | SHOW 現在是 labelShow HIDE 了 labelHide |
其他變更:
- 更新或刪除標籤時,Gmail API 會參考 ID 來參照標籤,而不是依名稱。
管理篩選器
如要在 Gmail API 中管理篩選器,請使用「Filters」資源。
舊設定 | 新設定 | 附註 |
---|---|---|
來自 | criteria.from | |
到 | criteria.to | |
subject | criteria.subject | |
hasTheWord | criteria.query | |
doesNotHaveTheWord | criteria.negatedQuery | |
hasAttachment | criteria.hasAttachment | |
shouldArchive | action.removeLabelIds | 使用 INBOX 做為標籤 ID |
shouldMarkAsRead | action.removeLabelIds | 使用 UNREAD 做為標籤 ID |
shouldStar | action.addLabelIds | 使用 STARRED 做為標籤 ID |
標籤 | action.addLabelIds | 使用標籤的 ID 新增 |
forwardTo | action.forward | |
shouldTrash | action.addLabelIds | 使用 TRASH 做為標籤 ID |
neverSpam | action.removeLabelIds | 使用 SPAM 做為標籤 ID |
其他變更:
- 如果新增的使用者標籤不存在,則需要使用 labels.create 方法明確建立。
管理寄件地址別名
如要在 Gmail API 中管理傳送時使用的別名,請使用 SendAs 資源。
舊設定 | 新設定 |
---|---|
名稱 | displayName |
地址 | sendAsEmail |
replyTo | replyToAddress |
makeDefault | isDefault |
管理網頁剪輯
已無法再透過 API 使用網頁剪輯設定。
管理自動轉寄設定
如要管理 Gmail API 中的自動轉寄功能,請使用設定資源。
舊設定 | 新設定 | 附註 |
---|---|---|
enable | 已啟用 | |
forwardTo | emailAddress | |
動作 | disposition | KEEP 現在leaveInInbox ARCHIVE 是 archive DELETE 現在是 trash MARK_READ markRead |
其他變更:
- 必須先建立並驗證轉寄地址,才能使用轉寄地址
- 您可以透過 ForwardingAddresses 資源,管理轉送位址。
管理 POP 設定
如要管理 Gmail API 中的 POP 存取權,請使用「設定」資源。
舊設定 | 新設定 | 附註 |
---|---|---|
enable | accessWindow | 停用時設為 disabled |
enableFor | accessWindow | ALL_MAIL 現在是 allMail MAIL_FROM_NOW_ON 了 fromNowOn |
動作 | disposition | KEEP 現在leaveInInbox ARCHIVE 是 archive DELETE 現在是 trash MARK_READ markRead |
管理 IMAP 設定
如要管理 Gmail API 中的 IMAP 存取權,請使用設定資源。
舊設定 | 新設定 |
---|---|
enable | 已啟用 |
管理休假自動回覆設定
如要在 Gmail API 中管理休假自動回覆功能,請使用「設定」資源。
舊設定 | 新設定 |
---|---|
contactsOnly | restrictToContacts |
domainOnly | restrictToDomain |
enable | enableAutoReply |
endDate | endTime |
訊息 | responseBodyHtml responseBodyPlainText |
startDate | startTime |
subject | responseSubject |
管理簽名設定
如要管理 Gmail API 中的電子郵件簽名,請使用 SendAs 資源。
舊設定 | 新設定 |
---|---|
簽名 | 簽名 |
其他變更:
- 系統現在會依別名管理簽名。
管理語言設定
如要管理 Gmail API 中的語言設定,請使用「Settings」資源。
舊設定 | 新設定 |
---|---|
language | displayLanguage |
詳情請參閱管理語言設定指南。
管理委派設定
如要在 Gmail API 中管理委派,請使用「Delegates」資源。
舊設定 | 新設定 |
---|---|
地址 | delegateEmail |
status | verificationStatus |
其他變更:
- 一般
- 如要使用任何委派方法 (包括 delegates.create),委派者使用者必須為 Gmail 啟用。舉例來說,委派者使用者無法在Google Workspace中停權。
- 電子郵件別名無法用於任何新方法的委派電子郵件輸入。委派使用者必須使用自己的主要電子郵件地址來稱呼對方。
- delegates.create
- 您現在可使用這個方法,在屬於相同機構的多個網域之間建立委派關係。 Google Workspace
- 這個方法現可用於要求在下次登入時變更密碼的使用者。
- 如果成功,這個方法會在回應主體中傳回 Users.settings.delegates 資源,而非空白的回應主體。
- 如果委派者或委派使用者處於停用狀態 (例如在 Google Workspace中遭到停權),此方法就會失敗,並顯示 HTTP 4XX 錯誤,而非 HTTP 500 錯誤。
- delegates.delete
- 這個方法現在可用於刪除具有任何 verificationStatus 的委派,而不只是
accepted
或expired
的委派。
- 這個方法現在可用於刪除具有任何 verificationStatus 的委派,而不只是
- delegates.get
- 這是新的方法,可能根據需要,而不是 delegates.list 方法。
管理一般設定
您無法再透過 API 使用一般設定。