Skip to content
Putting technology to work.
Insights to guide decisions and action.

Search articles

Postmaster Tools API v1 shutdown and migrating to v2

Table of contents · 6 items

If the people in charge of email delivery chart Gmail spam rates or SPF and DKIM success rates every day, those numbers may come from the Postmaster Tools API. It takes less effort than checking the screen, and it can be built into monitoring of the delivery system. If v1 suddenly stopped responding one day, the charts would go blank and you would not even notice anything was wrong.

In the Gmail API release notes, Google announced the deprecation of v1 and v1beta1 on November 10, 2026. When we checked on November 20 (Japan time), v1 and v1beta1 returned 404 both at the API endpoint and for the Discovery document. Only v2 is responding. In this article, we use Google's announcement, guides, and API definitions, along with actual responses, to outline what changes when you move aggregation or monitoring built on v1 to v2.

v1 and v1beta1 no longer respond

We sent unauthenticated requests to each version and recorded the status returned (November 20, 2026, 00:39 UTC).

DestinationResult
v1/domains・v1beta1/domains404 (Google's generic "Not Found" page)
v9/domains (nonexistent version, for comparison)404 (same page)
v2/domains401 (UNAUTHENTICATED; authentication required)
Discovery document v1 and v1beta1404
Discovery document v2200(revision 20261118)

v1 responds the same way as a nonexistent version, while v2 returns a normal rejection saying authentication is missing. We have not checked with authenticated requests, but at the very least the v1 endpoint is no longer usable.

In the official repository that mirrors Google's Discovery documents daily (googleapis/discovery-artifact-manager), the v1 and v1beta1 definitions were also removed in the November 17, 2026 update. The last version of the v1 definition had remained at May 29, 2025 (revision 20250529).

The deprecation was announced in the November 10, 2026 entry of the Gmail API release notes. The original text reads "Versions v1 and v1beta1 of the Gmail Postmaster Tools API are deprecated and being turned down." and states that the v1 reference was removed and v1 URLs now redirect to the v2 reference. domains.trafficStats.get and domains.trafficStats.list redirect to domains.domainStats.query. The announcement gives no shutdown date. v2 became generally available (GA) in the February 3, 2026 release notes.

The scope is now split into four

In v1 and v1beta1, there was only one scope, the read-only postmaster.readonly. The v2 definition does not include this scope; it has been replaced by the following four. The descriptions are translations of the text in the definition.

  • postmaster.traffic.readonly: read delivery metrics for registered domains
  • postmaster.domain: view and manage registered domains (the API setup guide describes it as "read-only access to domain information")
  • postmaster.user: view and manage users assigned to domains
  • postmaster: a permission combining the three above

Daily statistics (domainStats) and compliance status (complianceStatus) require postmaster.traffic.readonly or postmaster. The domain list (domains.list) requires postmaster.domain or postmaster. By definition, a token obtained with the v1 scope does not meet the requirements of any v2 method. Migration requires adding the new scopes to the OAuth consent screen and obtaining tokens again.

If your only goal is aggregation, the combination of postmaster.traffic.readonly and postmaster.domain is the closest to v1's read-only permission. postmaster, which also covers adding and removing domains and managing users, is too broad for an aggregation system.

The way statistics are retrieved has changed

In v1, you retrieved trafficStats by specifying a domain and date, and a single day's fields came back together. In v2, you send the metrics you want, the period, and the aggregation unit to 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"
}

The example above was put together by the editorial team from the definitions in the REST reference; we have not actually sent it and checked the result. According to the definitions, the aggregation unit is either daily (DAILY, the default) or a total for the period (OVERALL), and each call returns 10 items by default and up to 200. domainStats:batchQuery, which queries multiple domains together, can include up to 100 requests per call.

Note that the code examples in Google's migration guide (Migrate to Postmaster Tools API v2) and its statistics retrieval guide pass the period as startDate and endDate. The requests in the REST reference and the Discovery document do not have these two fields; the period is specified with timeQuery. Because the documents describe it differently, check which form actually works with the client library you use.

Mapping v1 fields to v2 metrics based on the descriptions in the definitions gives the following diagram.

Diagram showing how Postmaster Tools API v1 fields map to v2 metrics. Spam rate maps to SPAM_RATE; SPF, DKIM, and DMARC success rates map to AUTH_SUCCESS_RATE with an auth_type condition; TLS percentage maps to TLS_ENCRYPTION_RATE with a traffic_direction condition; delivery errors map to DELIVERY_ERROR_COUNT and RATE; and the feedback loop maps to FEEDBACK_LOOP_ID and FEEDBACK_LOOP_SPAM_RATE. The v2 definition has no metrics corresponding to domain reputation or IP reputation

The last row of the diagram is the point with the biggest impact on migration. Metrics corresponding to v1's domainReputation (domain reputation) and ipReputations (sending IP reputation) are not in the standardMetric list in the v2 definition. If you were charting reputation trends, you cannot get those series from the API in the same form. The Postmaster Tools help (Postmaster Tools dashboards) still listed IP reputation and domain reputation dashboards as of November 20, but we have not checked whether they can still be viewed on the screen.

Instead, v2 adds domains.getComplianceStatus, which returns whether you meet Gmail's sender requirements. For each requirement (SPF, DKIM, DMARC policy and alignment, message format, DNS settings, encryption, user-reported spam rate, one-click unsubscribe, and honoring unsubscribe requests), it returns COMPLIANT or NEEDS_WORK. The methods for registering and verifying domains and managing users, and the overall delivery status assessment (deliverabilityStatusVerdict), are still described as "Developer Preview" in the Discovery document. Meanwhile, the June 24, 2026 entry in the release notes describes them as Generally Available.

Migration steps (editorial suggestion)

  1. Find where v1 is called. Search your code and settings for gmailpostmastertools, v1/domains, v1beta1, and postmaster.readonly. If you call it through a library, also check whether your client version includes the v2 definitions. The migration guide also makes updating the client library the first step.
  2. Change scopes and obtain tokens again. Add postmaster.traffic.readonly and postmaster.domain to the scopes on the consent screen and reauthorize with the operations account. Replace any stored refresh tokens as well.
  3. Rebuild aggregation around metrics. Change the process that builds one row per day into one that rearranges per-metric results (identified by the metric name). It is realistic to drop the reputation series and keep compliance status as a separate table.
  4. Treat blank charts as an anomaly. When the endpoint stops, as in this case, a design that swallows errors simply stops producing numbers. Add notifications for failed retrievals and days with zero results along with the migration. According to the reference, v2's domainStats.query returns only days that have data. The statistics guide also says statistics are available only for domains that send to 50 or more users per day. Record days without data and retrieval failures separately.

We covered how to set up sending domain authentication (SPF, DKIM, DMARC) itself in our article on email authentication. v2 compliance status can also serve as a way to check from the outside whether those settings are taking effect. We outline the sending limits for bulk announcement emails from Google Workspace in our article on sending limits.

Scope of verification

On November 20, 2026, we checked the responses to unauthenticated requests to each version of the Postmaster Tools API, the v2 Discovery document (revision 20261118), the v1 and v1beta1 definitions in googleapis/discovery-artifact-manager and the November 17 update that removed them, the Gmail API release notes, the migration, statistics retrieval, and API setup guides, the v2 REST reference, and the Postmaster Tools help (document research and response checks). We did not send authenticated requests. We have not retrieved actual values with v2, compared values with v1, or checked the Postmaster Tools screen.

GleamHub's free IT and Google Workspace consultations cover development that connects Gmail or Google Workspace with other systems and reviewing email delivery monitoring. Please reach out through our contact form.

References

Share this articleXFacebook
Kakeru Suzuki

Fascinated by the possibilities of technology, has had a deep interest in programming and digital art since student days

Turn this article's theme into your company's next step

The right way forward with Workspace for your company.

We organize data to migrate, sharing rules, and governance structures to map out the journey from implementation to daily operations.

  • Migration and initial setup
  • Sharing and permission organization
  • Governance structure
Consult on Workspace implementation and operations

You can consult with us from the initial conceptual stage. Details from this article will be carried over to the inquiry form.

Receive the latest articles by email