從 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 中管理自動轉寄功能，請使用「Settings」資源。

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

其他變更：

  • 轉寄地址必須先建立並驗證，才能使用
  • 轉寄地址可透過 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 存取權，請使用「設定」資源。

舊設定 新設定
啟用 已啟用

管理休假自動回覆設定

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

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

管理簽名設定

如要在 Gmail API 中管理電子郵件簽名，請使用「SendAs」SendAs資源。

舊設定 新設定
簽名 簽名

其他變更：

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

管理語言設定

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

舊設定 新設定
language displayLanguage

詳情請參閱管理語言設定指南。

管理委派設定

如要在 Gmail API 中管理委派功能，請使用「Delegates」資源。

舊設定 新設定
地址 delegateEmail
狀態 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 不再提供一般設定。