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
ラベル name
unreadCount messagesUnread
visibility labelListVisibility SHOW が labelShow になりました
HIDE が labelHide になりました

その他の変更点:

  • ラベルを更新または削除する場合、Gmail API は名前ではなく ID でラベルを参照します。

フィルタを管理する

Gmail API でフィルタを管理するには、 settings.filters リソースを使用します。

以前の設定 新しい設定 メモ
from criteria.from
to criteria.to
件名 criteria.subject
hasTheWord criteria.query
doesNotHaveTheWord criteria.negatedQuery
hasAttachment criteria.hasAttachment
shouldArchive action.removeLabelIds ラベル ID として INBOX を使用します
shouldMarkAsRead action.removeLabelIds ラベル ID として UNREAD を使用します
shouldStar action.addLabelIds ラベル ID として STARRED を使用します
ラベル action.addLabelIds 追加するラベルの ID を使用します
forwardTo action.forward
shouldTrash action.addLabelIds ラベル ID として TRASH を使用します
neverSpam action.removeLabelIds ラベル ID として SPAM を使用します

その他の変更点:

  • ユーザーラベルを追加する場合、まだ存在しない場合は、明示的に作成する必要があります 使用して labels.create メソッド。

送信元エイリアスを管理する

Gmail API で送信元エイリアスを管理するには、 settings.sendAs リソースを使用します。

以前の設定 新しい設定
name 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
件名 responseSubject

署名設定を管理する

Gmail API でメール署名を管理するには、 settings.sendAs リソースを使用します。

以前の設定 新しい設定
signature signature

その他の変更点:

  • 署名はエイリアスごとに管理されるようになりました。

言語の設定を管理する

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 500 エラーではなく HTTP 4XX エラーで失敗します。
  • settings.delegates.delete
    • このメソッドを使用して、accepted または expired の委任だけでなく、任意の VerificationStatus, の委任を削除できるようになりました。
  • settings.delegates.get
    • これは新しいメソッドです。必要に応じて、 settings.delegates.list メソッドよりも優先される場合があります。

全般的な設定を管理

全般的な設定は Gmail API では使用できません。