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).
| Destination | Result |
|---|---|
v1/domains・v1beta1/domains | 404 (Google's generic "Not Found" page) |
v9/domains (nonexistent version, for comparison) | 404 (same page) |
v2/domains | 401 (UNAUTHENTICATED; authentication required) |
| Discovery document v1 and v1beta1 | 404 |
| Discovery document v2 | 200(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 domainspostmaster.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 domainspostmaster: 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.

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)
- Find where v1 is called. Search your code and settings for
gmailpostmastertools,v1/domains,v1beta1, andpostmaster.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. - Change scopes and obtain tokens again. Add
postmaster.traffic.readonlyandpostmaster.domainto the scopes on the consent screen and reauthorize with the operations account. Replace any stored refresh tokens as well. - Rebuild aggregation around metrics. Change the process that builds one row per day into one that rearranges per-metric results (identified by the
metricname). It is realistic to drop the reputation series and keep compliance status as a separate table. - 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.queryreturns 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
- Postmaster Tools API v2 Discovery document (gmailpostmastertools.googleapis.com)
- googleapis/discovery-artifact-manager — commit ef9dbbd (2026-11-17, an update that includes removing the v1 and v1beta1 definitions)
- googleapis/discovery-artifact-manager — gmailpostmastertools.v2.json
- Gmail API release notes (deprecation of v1 and v1beta1 in the November 10, 2026 entry)
- Migrate to Postmaster Tools API v2(Google for Developers)
- Method: domains.domainStats.query (v2 REST reference)
- Retrieve email statistics(Google for Developers)
- Set up the API(Google for Developers)
- Postmaster Tools dashboards (Gmail Help)









