このドキュメントでは、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 で全般設定を使用できなくなりました。