Gmail API は、Gmail のメールボックスの読み取り・送信・整理・設定変更を行う RESTful API。ユーザーの認可を得て Gmail データへ触れる Web アプリの、多くの場面で最適な選択肢とされている。
| リソース | 内容 |
|---|---|
messages | 送信者・宛先・件名・本文を持つメール。作成後は内容を変更できない |
threads | 関連するメッセージを会話としてまとめたもの |
labels | 整理用の印。システムラベル (INBOX・TRASH・SPAM 等) は作成・削除できない。ユーザーラベルは作成・変更・削除できる |
drafts | 未送信のメッセージ。内容を差し替えられる。送信すると下書きは消え、SENT ラベルのメッセージができる |
history | メールボックスの変更履歴。historyId を起点に差分を取る (「プッシュ通知と送信」を参照) |
settings | 送信元エイリアスと署名・転送・フィルタ・不在通知・S/MIME・POP/IMAP・委任・言語 |
| 種類 | Gmail での使いどころ |
|---|---|
| API キー | 公開データ用。Workspace の大半のデータは OAuth 2.0 が必要で、メールには通常使えない |
| OAuth 2.0 クライアント ID | ユーザー所有のメールに触れる主要な手段。同意画面での承認が要る。長期の利用にはリフレッシュトークンを取る |
| サービスアカウント | 単独ではユーザーのメールに触れない。ドメイン全体の委任を設定すると組織内のユーザーのメールに触れる。有効化できるのはスーパー管理者だけ |
クライアントシークレットは、アプリのコードに平文で含めず安全に保管する。
出典: 認証と認可の概要 (Google for Developers。Workspace API 全般の説明)
区分は Non-sensitive / Sensitive / Restricted の 3 段階。要る範囲だけを求める。
スコープ (https://www.googleapis.com/auth/ 以下) | 区分 | 概要 |
|---|---|---|
gmail.labels | Non-sensitive | ラベルの閲覧と編集 |
gmail.addons.current.action.compose | Non-sensitive | アドオン操作時に下書きの管理とメール送信 |
gmail.addons.current.message.action | Non-sensitive | アドオン操作時にメッセージを閲覧 |
gmail.addons.current.message.metadata | Sensitive | アドオン実行時にメタデータを閲覧 |
gmail.addons.current.message.readonly | Sensitive | アドオン実行時にメッセージを閲覧 |
gmail.send | Sensitive | ユーザーの代理でメールを送信 |
gmail.readonly | Restricted | メールと設定の閲覧 |
gmail.compose | Restricted | 下書きの管理とメール送信 |
gmail.insert | Restricted | メールボックスへのメール追加 |
gmail.modify | Restricted | 閲覧・作成・送信。ゴミ箱を経由した即時の完全削除はできない |
gmail.metadata | Restricted | ラベルやヘッダーの閲覧 (本文は不可) |
gmail.settings.basic | Restricted | メール設定とフィルタの閲覧・変更 |
gmail.settings.sharing | Restricted | 重要な設定の管理。管理者用で、ドメイン全体の委任を受けたサービスアカウントのみ |
https://mail.google.com/ | Restricted | 閲覧・作成・送信に加え完全削除も可能 |
gmail.readonly 等) は、本文を読めないはずの gmail.metadata まで含めて Restricted。送信だけなら Sensitive の gmail.send で足りる。https://mail.google.com/ は、即時かつ完全な削除が要るときだけ求めるよう公式が注記している。出典: Gmail API のスコープ (Google for Developers)
admin_policy_enforced)openid・userinfo.email・userinfo.profile だけを求める場合を除く)出典: OAuth 2.0 の概要 (Google for Developers)
| 種類 | 上限 |
|---|---|
| 1 分あたり・プロジェクト | 1,200,000 ユニット |
| 1 分あたり・ユーザー / プロジェクト | 6,000 ユニット |
| 1 日あたり・プロジェクト (課金のしきい値) | 80,000,000 ユニット |
| メソッド | ユニット |
|---|---|
messages.list / messages.modify / threads.list | 5 (threads.list は 10) |
messages.get | 20 (format が full・raw・html なら 60) |
threads.get | 40 (format が full なら 120) |
messages.send / drafts.send | 100 |
messages.batchModify / batchDelete | 50 |
history.list | 2 |
watch | 100 |
labels.list / labels.get / getProfile | 1 |
messages.get は 60 ユニット。ユーザーあたり毎分 6,000 ユニットなら、本文付きで毎分およそ 100 通が目安になる。ヘッダーだけの取得 (20 ユニット) なら 3 倍。全ユニット表は出典を参照。gmail-api-push@system.gserviceaccount.com にトピックへの publish 権限を与えるusers/me/watch にトピックと対象ラベルを指定して呼ぶ。現在の historyId と expiration が返るmessage.data (Base64URL の JSON) にメールアドレスと新しい historyId が入るhistoryId で history.list を呼び、差分を取る。処理後に新しい値を保存するwatch は 7 日以内に再実行しないと、そのユーザーの更新が届かなくなる。公式は 1 日 1 回の再実行を勧める。通知は通常数秒で届くが、まれに遅延・欠落するため、通知が来ないときの備えとして history.list の定期呼び出しを用意する。出典: Gmail のプッシュ通知 (Google for Developers)
1. RFC 2822 準拠の MIME メッセージを作る (添付はマルチパート)
2. base64url でエンコードして、メッセージの raw に入れる
3. messages.send (下書きなら drafts.send) を呼ぶSubject の一致と、References・In-Reply-To の RFC 2822 どおりの設定出典: メールの送信 (Google for Developers)
公式のガイド・リファレンス (送信ガイド、アップロードのガイド、messages.send のリファレンス、クォータ) には、数値の記載が無かった。Google が配布する API 定義 (Discovery ドキュメント) の media upload の maxSize には、次の値がある。
| メソッド | maxSize (バイト) | 換算 |
|---|---|---|
messages.send | 36,700,160 | 35 MiB |
drafts.create / drafts.update / drafts.send | 36,700,160 | 35 MiB |
messages.import / messages.insert | 157,286,400 | 150 MiB |
/upload/...) の上限。JSON の raw に base64url で入れる経路に同じ上限が掛かるかは、確かめられていない。base64url で約 3 分の 1 大きくなるため、添付できる実サイズはこれより小さい。