從 Email Settings API 遷移

本文說明如何將應用程式從已淘汰的 Email Settings API 遷移至 Gmail API。

授權要求

與 Email Settings API 相同，Gmail API 也會使用 OAuth 2.0 通訊協定授權要求。主要差異在於 Gmail API 權限的範圍是個別使用者，而非整個網域。也就是說，授權網域管理員帳戶後，您無法遷移網域中其他使用者的郵件。您必須使用具有網域層級授權的標準服務帳戶，並將這些帳戶加入 Google 管理控制台的允許清單，才能產生適當的驗證權杖。

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
visibility labelListVisibility 「SHOW」現為「labelShow」
HIDE現為「labelHide」

其他變更：

  • 更新或刪除標籤時，Gmail API 會依 ID 參照標籤，而非依名稱。

管理篩選條件

如要在 Gmail API 中管理篩選器，請使用 settings.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 中管理「以這個地址或別名寄信」別名，請使用 settings.sendAs 資源。

舊設定 新設定
名稱 displayName
地址 sendAsEmail
replyTo replyToAddress
makeDefault isDefault

管理網頁剪報

Gmail API 不支援網頁剪輯設定。

管理自動轉寄功能

如要在 Gmail API 中管理自動轉寄功能，請使用 settings 資源。

舊設定 新設定 附註
啟用 已啟用
forwardTo emailAddress
動作 disposition 「KEEP」現為「leaveInInbox」
「ARCHIVE」現為「archive」
「DELETE」現為「trash」
「MARK_READ」現為「markRead」

其他變更：

  • 您必須先建立並驗證轉寄地址，才能使用這些地址。
  • 如要管理轉送地址，請使用 settings.forwardingAddresses 資源。

管理 POP 設定

如要在 Gmail API 中管理 POP 存取權，請使用 settings 資源。

舊設定 新設定 附註
啟用 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 存取權，請使用 settings 資源。

舊設定 新設定
啟用 已啟用

管理休假自動回覆設定

如要在 Gmail API 中管理休假自動回覆，請使用 settings 資源。

舊設定 新設定
contactsOnly restrictToContacts
domainOnly restrictToDomain
啟用 enableAutoReply
endDate endTime
訊息 responseBodyHtml
responseBodyPlainText
startDate startTime
subject responseSubject

管理簽名設定

如要在 Gmail API 中管理電子郵件簽名，請使用 settings.sendAs 資源。

舊設定 新設定
簽名 簽名

其他變更：

  • 現在你可以為每個別名管理簽名。

管理語言設定

如要在 Gmail API 中管理語言設定，請使用 settings 資源。

舊設定 新設定
language displayLanguage

詳情請參閱「管理語言設定」。

管理委派設定

如要在 Gmail API 中管理委派功能，請使用 settings.delegates 資源。

舊設定 新設定
地址 delegateEmail
狀態 verificationStatus

其他變更：

  • 一般
    • 如要使用任何委派方法 (包括 settings.delegates.create)，委派者使用者必須啟用 Gmail。也就是說，例如，委派者使用者無法在 Google Workspace 中遭到停權。
    • 您無法使用電子郵件別名做為任何新方法的委派電子郵件輸入內容。您必須使用主要電子郵件地址參照委派使用者。
  • settings.delegates.create
    • 您現在可以使用這個方法，在屬於同一個 Google Workspace 機構的多個網域中建立委派關係。
    • 現在，您可以使用這個方法，要求使用者在下次登入時變更密碼。
    • 如果成功，這個方法會在回應本體中傳回 settings.delegates 資源，而不是空白的回應本體。
    • 如果委派者或受委派使用者遭到停用 (例如在 Google Workspace 中遭到停權)，這個方法會失敗並傳回 HTTP 4XX 錯誤，而非 HTTP 500 錯誤。
  • settings.delegates.delete
    • 您現在可以使用這個方法，透過任何 VerificationStatus 刪除委派人員，而不只是 accepted 或 expired。
  • settings.delegates.get

管理一般設定

Gmail API 不支援一般設定。