從 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 中的標籤，請使用標籤資源。

舊設定 新設定 附註
labelId id
標籤 名稱
unreadCount messagesUnread
顯示設定 labelListVisibility SHOW 現已改名為 labelShow
HIDE 現已改名為 labelHide

其他變更：

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

管理篩選器

如要管理 Gmail API 中的篩選器，請使用篩選器資源。

舊設定 新設定 附註
來自 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 中的自動轉寄功能，請使用設定資源。

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

其他變更：

  • 必須先建立並驗證轉送地址，才能使用
  • 您可以透過 ForwardingAddresses 資源管理轉寄地址。

管理 POP 設定

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

舊設定 新設定 附註
啟用 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 中管理休假自動回覆功能，請使用「設定」資源。

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

管理簽名設定

如要在 Gmail API 中管理電子郵件簽名，請使用 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 提供。