Gmail API のクォータ変更(2026年5月)|旧仕様との違い・対象プロジェクト・format による消費量の差

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

Gmail API と Microsoft Graph API の全体的な比較は、こちらの記事にまとめています。

あわせて読みたい
メールAPI 完全ガイド — Microsoft Graph API & Gmail API 2026年5月仕様変更あり この記事では、見出しの項目ごとに Gmail API と Microsoftと 両APIを並べて比較調査をまとめてます 環境のセットアップやAPI使用するための準備など Google Cloud の「...
目次

何が変わったか

項目改定前(2026年4月まで)改定後(2026年5月以降の新規プロジェクト)
プロジェクトごと(1分あたり)1,200,000 units1,200,000 units(変更なし)
ユーザーごと(1分あたり)15,000 units6,000 units
1日あたり(プロジェクトごと)記載なし80,000,000 units(課金の閾値)
messages.get520(format が full / raw / html のときは 60)
messages.attachments.get520
threads.get1040(format が full のときは 120)
messages.list55
messages.send100100

改定前の値は、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取得できる内容コスト
minimalID とラベルのみ20
metadataID、ラベル、ヘッダー20
full(既定値)本文をパースした payload を含む全データ60
rawRFC 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 / minimal20(6,000 − 5) ÷ 20 ≒ 299件
改定後・full(既定値) / raw60(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分単位なので、並列数を絞って平準化する

参考

目次