從 Email Settings API 遷移

本文說明 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 的委派。
  • delegates.get
    • 這是新的方法，可能根據需要，而不是 delegates.list 方法。

管理一般設定

您無法再透過 API 使用一般設定。