Email Settings API からの移行

このドキュメントでは、Email Settings API と Gmail API の主な違いについて説明します。このガイドは、アプリを Gmail API に移行する際に役立ちます。

リクエストの承認

Email Settings API と同様に、Gmail API は OAuth 2.0 プロトコルを使用してリクエストを承認します。主な違いの 1 つは、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 でラベルを管理するには、Labels リソースを使用します。

以前の設定 新しい設定 メモ
labelId id
ラベル name
unreadCount messagesUnread
visibility labelListVisibility SHOW を labelShow に変更
HIDE を labelHide に変更

その他の変更点:

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

フィルタの管理

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

以前の設定 新しい設定 メモ
元 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 で送信者名エイリアスを管理するには、SendAs リソースを使用します。

以前の設定 新しい設定
name 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 アクセスを管理するには、Settings リソースを使用します。

以前の設定 新しい設定
有効にする 有効

休暇中の自動返信の設定を管理する

Gmail API で不在時の自動返信を管理するには、Settings リソースを使用します。

以前の設定 新しい設定
contactsOnly restrictToContacts
domainOnly restrictToDomain
有効にする enableAutoReply
endDate endTime
メッセージ responseBodyHtml
responseBodyPlainText
startDate startTime
件名 responseSubject

署名設定の管理

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

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

その他の変更点:

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

言語設定の管理

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

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

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

委任設定の管理

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

以前の設定 新しい設定
住所 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 経由では利用できなくなりました。