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 を使用します。設定は主に Key-Value ペアで構成されるため、ペイロードはバージョン間で概念的に類似しています。

ラベルの作成例:

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
ラベル name
unreadCount messagesUnread
visibility 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 リソースを使用します。

以前の設定 新しい設定
name displayName
address sendAsEmail
replyTo replyToAddress
makeDefault isDefault

ウェブクリップの管理

API 経由でのウェブクリップの設定はご利用いただけなくなりました。

自動転送設定の管理

Gmail API で自動転送を管理するには、設定リソースを使用します。

以前の設定 新しい設定 メモ
enable 有効
forwardTo emailAddress
action 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 になりました
action 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
message responseBodyHTML
responseBodyPlainText
startDate startTime
subject responseSubject

署名設定の管理

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

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

その他の変更点:

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

言語設定の管理

Gmail API で言語設定を管理するには、設定リソースを使用します。

以前の設定 新しい設定
language displayLanguage

詳しくは、言語設定の管理ガイドをご覧ください。

委任設定を管理する

Gmail API で委任を管理するには、代理人リソースを使用します。

以前の設定 新しい設定
address delegateEmail
status verificationStatus

その他の変更点:

  • 全般
    • いずれかの委任方法（delegates.create を含む）を使用するには、委任ユーザーの Gmail が有効になっている必要があります。つまり、Google Workspaceで委任者ユーザーを停止することはできません。
    • どの新しい方法でも、メール エイリアスを委任メール入力として使用することはできません。委任ユーザーは、メインのメールアドレスで参照する必要があります。
  • delegates.create
    • このメソッドを使用して、同じ組織に属する複数のドメイン間で委任関係を作成できるようになりました。 Google Workspace
    • これで、次回ログイン時にパスワードの変更を要求するユーザーに対して、このメソッドを使用できるようになりました。
    • 成功した場合、このメソッドは空のレスポンス本文ではなく、レスポンスの本文で Users.settings.delegates リソースを返します。
    • 委任ユーザーまたは委任ユーザーのいずれかが無効になっている場合（たとえば、 Google Workspaceで一時停止されている場合）、このメソッドは HTTP 500 エラーではなく HTTP 4XX エラーで失敗します。
  • delegates.delete
    • このメソッドを使用して、accepted または expired であるデリゲートだけでなく、任意の verificationStatus を持つデリゲートを削除できるようになりました。
  • delegates.get
    • これは新しいメソッドであり、必要に応じて delegates.list メソッドよりも適している可能性があります。

全般設定の管理

API で全般設定を使用できなくなりました。