本文へ移動
技術を、自社の仕事に。
判断と実行を助けるメディア

記事を検索

Postmaster Tools API v1停止とv2移行

目次 · 6項目

メールの配信の担当が、Gmail宛ての迷惑メール率やSPF・DKIMの成功率を毎日グラフにしている場合、その数字はPostmaster Tools APIから取っていることがあります。画面で見るより手間が少なく、配信システムの監視にも組み込めるからです。そのv1が、ある日を境に応答しなくなっていたら、グラフは空になり、異常にも気づけません。

GoogleはGmail APIのリリースノートで、2026年11月10日にv1とv1beta1の廃止を告知しました。11月20日(日本時間)に確かめたところ、v1とv1beta1は、APIの入口でもDiscovery文書でも404を返しました。応答しているのはv2だけです。本記事では、v1を前提にした集計や監視をv2へ移すときに変わる点を、Googleの告知・ガイド・APIの定義と、実際の応答から整理します。

v1とv1beta1は応答しない

認証なしで各版にリクエストを送り、返ってきた状態を記録しました(2026年11月20日00:39 UTC)。

送り先結果
v1/domains・v1beta1/domains404(Googleの汎用の「Not Found」のページ)
v9/domains(存在しない版、比較用)404(同じページ)
v2/domains401(UNAUTHENTICATED。認証を求める)
Discovery文書 v1・v1beta1404
Discovery文書 v2200(revision 20261118)

v1は存在しない版と同じ返り方で、v2は「認証がない」という正常な拒否を返しています。認証付きのリクエストでの確認はしていませんが、少なくともv1の入口はもう使えない状態です。

GoogleのDiscovery文書を毎日写している公式のリポジトリ(googleapis/discovery-artifact-manager)でも、2026年11月17日の更新でv1とv1beta1の定義が削除されました。v1の定義の最後の版は2025年5月29日(revision 20250529)のままでした。

廃止の告知は、Gmail APIのリリースノートの2026年11月10日の項です。原文は「Versions v1 and v1beta1 of the Gmail Postmaster Tools API are deprecated and being turned down.」で、v1のリファレンスを削除し、v1のURLをv2のリファレンスへ転送したとあります。domains.trafficStats.get と domains.trafficStats.list の転送先は domains.domainStats.query です。告知に停止の日付は書かれていません。v2は2026年2月3日のリリースノートで一般提供(GA)になっていました。

スコープが4つに分かれた

v1とv1beta1のスコープは、読み取りの postmaster.readonly の1つだけでした。v2の定義にこのスコープはなく、次の4つに変わっています。説明は定義の記述を訳したものです。

  • postmaster.traffic.readonly:登録したドメインの配信の指標を読む
  • postmaster.domain:登録したドメインを見る・管理する(APIの設定のガイドでは「read-only access to domain information」)
  • postmaster.user:ドメインに付けた利用者を見る・管理する
  • postmaster:上の3つをまとめた権限

日ごとの統計(domainStats)と準拠の状況(complianceStatus)は、postmaster.traffic.readonly か postmaster を求めます。ドメインの一覧(domains.list)は postmaster.domain か postmaster です。v1のために取ったトークンのスコープは、定義の上ではv2のどのメソッドの条件にも当たりません。移行では、OAuthの同意の画面に新しいスコープを足し、トークンを取り直す作業が必要になります。

集計だけが目的なら、postmaster.traffic.readonly と postmaster.domain の組み合わせが、v1の読み取りの権限に近い範囲です。ドメインの追加・削除や利用者の管理まで含む postmaster は、集計の仕組みには広すぎます。

統計の取り方が変わった

v1は、ドメインと日付を指定して trafficStats を取り、1日分の項目がまとめて返る形でした。v2では domains.domainStats.query(POST)に、欲しい指標・期間・集計の単位を送ります。

{
  "metricDefinitions": [
    { "name": "spam", "baseMetric": { "standardMetric": "SPAM_RATE" } },
    { "name": "dkim", "baseMetric": { "standardMetric": "AUTH_SUCCESS_RATE" }, "filter": "auth_type = \"dkim\"" }
  ],
  "timeQuery": {
    "dateRanges": {
      "dateRanges": [
        { "start": { "year": 2026, "month": 11, "day": 1 }, "end": { "year": 2026, "month": 11, "day": 19 } }
      ]
    }
  },
  "aggregationGranularity": "DAILY"
}

上の例はRESTのリファレンスの定義から編集部が組んだもので、実際に送って結果を確かめたものではありません。定義によると、集計の単位は日ごと(DAILY、既定)か期間の合計(OVERALL)で、1回に返る件数は既定10件・最大200件です。複数のドメインをまとめて問い合わせる domainStats:batchQuery は、1回に100件までのリクエストを含められます。

なお、Googleの移行のガイド(Migrate to Postmaster Tools API v2)と統計の取得のガイドのコード例は、期間を startDate と endDate で渡しています。RESTのリファレンスとDiscovery文書のリクエストには、この2つの項目がなく、期間は timeQuery で指定します。資料どうしで書き方が違うため、使うクライアントのライブラリで実際に通る形を確かめてください。

v1の項目とv2の指標を、定義の説明をもとに対応づけると次の図になります。

Postmaster Tools APIのv1の項目とv2の指標の対応を示した図。迷惑メール率はSPAM_RATE、SPF・DKIM・DMARCの成功率はAUTH_SUCCESS_RATEにauth_typeの条件、TLSの割合はTLS_ENCRYPTION_RATEにtraffic_directionの条件、配信エラーはDELIVERY_ERROR_COUNTとRATE、フィードバックループはFEEDBACK_LOOP_IDとFEEDBACK_LOOP_SPAM_RATEに当たる。ドメインの評判とIPの評判に当たる指標はv2の定義にない

図の最後の行が、移行でいちばん影響が大きい点です。v1の domainReputation(ドメインの評判)と ipReputations(送信元のIPの評判)に当たる指標は、v2の定義の standardMetric の一覧にありません。評判の推移をグラフにしていた場合、その系列はAPIからは同じ形では取れません。Postmaster Toolsのヘルプ(Postmaster Tools dashboards)には、11月20日の時点でもIPの評判とドメインの評判のダッシュボードが載っていますが、画面で今も見られるかは確かめていません。

代わりにv2には、Gmailの送信者の要件を満たしているかを返す domains.getComplianceStatus が加わりました。SPF、DKIM、DMARCのポリシーと整合、メッセージの形式、DNSの設定、暗号化、利用者が報告した迷惑メール率、ワンクリックでの配信停止、配信停止の要求への対応、の各要件について、COMPLIANT か NEEDS_WORK が返ります。ドメインの登録・確認・利用者の管理のメソッドと、配信の状況の総合判定(deliverabilityStatusVerdict)は、Discovery文書の説明では今も「Developer Preview」と書かれています。一方、リリースノートの2026年6月24日の項は、これらを一般提供(Generally Available)としています。

移す手順(編集部の提案)

  1. v1を呼んでいる箇所を探す。 コードや設定を gmailpostmastertools、v1/domains、v1beta1、postmaster.readonly で検索します。ライブラリ経由で呼んでいる場合は、使っているクライアントの版がv2の定義を含んでいるかも確かめます。移行のガイドも、クライアントのライブラリの更新を最初の手順にしています。
  2. スコープを替えてトークンを取り直す。 同意の画面のスコープに postmaster.traffic.readonly と postmaster.domain を加え、運用のアカウントで認可し直します。保存しているリフレッシュトークンも入れ替えます。
  3. 集計を指標の単位で組み直す。 日ごとの1行を作る処理を、指標ごとの結果(metric の名前で識別)を並べ直す処理に変えます。評判の系列は外し、準拠の状況を別の表として持つのが現実的です。
  4. 空のグラフを異常として扱う。 今回のように入口が止まると、エラーを握りつぶす作りでは数字が出なくなるだけで終わります。取得の失敗や0件の日を通知する仕組みを、移行と一緒に入れておきます。v2の domainStats.query は、リファレンスによるとデータがある日の分だけを返します。また、統計のガイドには、1日に50人以上の利用者へ送っているドメインだけに統計が付くとあります。データがない日と取得の失敗は、分けて記録します。

送信ドメインの認証(SPF・DKIM・DMARC)そのものの整え方はメール認証の記事で扱いました。v2の準拠の状況は、その設定が届いているかを外から確かめる手段としても使えます。Google Workspaceから案内メールを一斉に送るときの送信の上限は送信上限の記事で整理しています。

確認した範囲

2026年11月20日に、Postmaster Tools APIの各版への認証なしのリクエストの応答、v2のDiscovery文書(revision 20261118)、googleapis/discovery-artifact-manager のv1・v1beta1の定義と、それを削除した11月17日の更新、Gmail APIのリリースノート、移行・統計の取得・APIの設定のガイド、v2のRESTのリファレンス、Postmaster Toolsのヘルプを確認しました(資料調査と、応答の確認)。認証付きのリクエストは送っていません。v2での実際の数値の取得、v1との数値の比較、Postmaster Toolsの画面の確認は未実施です。

GmailやGoogle Workspaceとほかの仕組みをつなぐ開発、メール配信の監視の見直しは、グリームハブのIT・Google Workspace 無料相談で承っています。お問い合わせからご相談ください。

参考資料

この記事を共有XFacebook
鈴木 翔

技術の可能性に魅了され、学生時代からプログラミングとデジタルアートの分野に深い関心を持つ

この記事のテーマを、自社の次の一歩へ

自社に合う、Workspaceの進め方を。

移行するデータ、共有ルール、管理体制を整理し、導入から日々の運用までの進め方を考えます。

  • 移行と初期設定
  • 共有・権限の整理
  • 管理体制
Workspaceの導入・運用を相談する

構想段階からご相談いただけます。この記事の情報を相談フォームに引き継ぎます。

最新記事をメールで受け取る