2026年5月1日に Gmail API の使用量上限(クォータ)が改定されました。この記事では、改定前後で何が変わったのか、どのプロジェクトが新しい上限の対象になるのか、実装にどう影響するのかを公式ドキュメントをもとに整理します。
Gmail API と Microsoft Graph API の全体的な比較は、こちらの記事にまとめています。

何が変わったか
| 項目 | 改定前(2026年4月まで) | 改定後(2026年5月以降の新規プロジェクト) |
|---|---|---|
| プロジェクトごと(1分あたり) | 1,200,000 units | 1,200,000 units(変更なし) |
| ユーザーごと(1分あたり) | 15,000 units | 6,000 units |
| 1日あたり(プロジェクトごと) | 記載なし | 80,000,000 units(課金の閾値) |
| messages.get | 5 | 20(format が full / raw / html のときは 60) |
| messages.attachments.get | 5 | 20 |
| threads.get | 10 | 40(format が full のときは 120) |
| messages.list | 5 | 5 |
| messages.send | 100 | 100 |
改定前の値は、2026年3月時点の公式ドキュメント(Internet Archive に保存された版)で確認しました。プロジェクト全体の上限は変わっておらず、変わったのはユーザーごとの上限と、本文や添付を取得するメソッドのコストです。
どのプロジェクトが新しい上限の対象になるか
公式ドキュメントでは、次のように区別されています。
- 2026年5月1日以降に作成した Google Cloud プロジェクト:新しい上限が適用される
- 2025年11月〜2026年4月の間に Gmail API を一度でも使ったプロジェクト:以前の上限のまま
既存プロジェクトの扱いがいつまで続くかは、現時点では書かれていません。手元のプロジェクトにどちらが適用されているかは、Google Cloud Console の「APIとサービス」→「Gmail API」→「割り当てとシステム上限」で確認できます。
80,000,000 units/日は上限ではなく課金の閾値
新しく加わった 80,000,000 units/日 は、ここで止められるという上限ではなく、これを超えると課金が発生する閾値です。公式ドキュメントでは次のように説明されています。
- 閾値を下回る使用量には課金されない
- 課金の詳細は2026年後半に発表され、変更が適用される少なくとも90日前に告知される
- この閾値の引き上げは申請できない
2026年11月時点では、まだ料金は発表されていません。
format を省略すると messages.get は 60 units 消費する
2026年10月下旬ごろの公式ドキュメント更新で、messages.get と drafts.get のコストに「format が full / raw / html のときは 60」という但し書きが追加されました(10月上旬のアーカイブ版では 20 のみ)。
注意したいのは、messages.get の format の既定値が full であることです(Gmail API のディスカバリードキュメントで "default": "full" と定義されています)。googleapis で gmail.users.messages.get({ userId: "me", id }) のように format を指定せずに呼ぶと、1回で 60 units を消費します。
| format | 取得できる内容 | コスト |
|---|---|---|
| minimal | ID とラベルのみ | 20 |
| metadata | ID、ラベル、ヘッダー | 20 |
| full(既定値) | 本文をパースした payload を含む全データ | 60 |
| raw | RFC 2822 形式のメール全体(base64url) | 60 |
一覧画面のように件名・差出人・日時だけ必要な場面では、format: "metadata" と metadataHeaders を指定すると消費量を3分の1に抑えられます。
list と get で1分間に何件取得できるか
ユーザー1人について、messages.list を1回呼び、その結果に含まれるメールを messages.get で取得する場合の試算です。単位を揃えるため、すべて1分あたりで計算しています。
| 条件 | get 1回のコスト | 1分あたりの最大取得件数 |
|---|---|---|
| 改定前 | 5 | (15,000 − 5) ÷ 5 ≒ 2,999件 |
| 改定後・metadata / minimal | 20 | (6,000 − 5) ÷ 20 ≒ 299件 |
| 改定後・full(既定値) / raw | 60 | (6,000 − 5) ÷ 60 ≒ 99件 |
改定前と比べると、metadata 指定でも約10分の1、format を省略した場合は約30分の1になります。メールの全件同期のように大量の get を発行する処理は、新しいプロジェクトでは設計を見直す必要があります。
「250 units/秒」「10億 units/日」はさらに古い仕様
ネット上の解説記事には「ユーザーあたり 250 units/秒」「プロジェクトあたり 1日 1,000,000,000 units」という値がよく出てきます。これは今回の改定より前の、さらに古い版のドキュメントの値です。2026年3月時点の公式ドキュメントはすでに1分あたりの表記(ユーザーごと 15,000 units/分)になっていたので、新旧を比べるときは 15,000 units/分 を基準にするのが正確です。
上限を超えたときの対策
上限を超えると、403(rateLimitExceeded / userRateLimitExceeded)または 429 が返ります。基本はジッター付きの指数バックオフで再試行しますが、新しい上限では消費量そのものを減らす工夫も効いてきます。
- 一覧表示には
format: "metadata"を使い、本文が必要になった時点で full を取得する - 初回の全件取得のあとは history.list(2 units)で差分だけ同期する
- スレッド単位で必要な場合でも、threads.get の full(120 units)は高いので、format を明示する
- ユーザーごとの上限は1分単位なので、並列数を絞って平準化する