Is there a V2 API available for Google Postmaster Tools?
Updated on 9 Oct 2026: We updated our API v2 guidance for OAuth setup and current reporting limits.
Yes. Google documents a stable Postmaster Tools API v2. You can use it to pull Gmail Postmaster statistics into a custom reporting environment, including a Tableau workflow, but Tableau still needs a connector layer such as a warehouse table, scheduled extract, or small internal service.
Google's API overview says the Postmaster Tools API gathers statistics on bulk email sent to Gmail users and lets you import or merge that data with other systems. That is the key point for reporting teams: the API is meant for export and integration, not just for a web UI.
- Answer: Yes, use the stable v2 API for programmatic access to Google Postmaster Tools statistics.
- Reporting: For Tableau, pull the API data into a database, file store, or BI-ready extract first.
- Tableau refreshes need an API integration and a supported data source or extract workflow.
- The v2 web interface launched in 2024. Its launch and the later API v2 release are separate events.
Google Postmaster Tools API v2 availability
Google Postmaster Tools v2 spam rate and sender compliance dashboard illustration.
Existing v1 integrations need method and data-model changes. Google's migration guide says v2 replaces v1 trafficStats with domainStats. It also adds date range queries, compliance status for SPF, DKIM, and DMARC, and batch queries across multiple domains. Existing integrations need a v2 client library plus method and schema changes.
The v2 API gives Gmail-specific reporting signals. It does not explain every authentication failure, domain spoofing event, non-Gmail inbox placement issue, IP blocklist (blacklist) listing, or cause behind a complaint spike.
Use v2 when you need scheduled access to Postmaster statistics, compliance status, and multi-domain reporting. Keep the web UI for quick investigation, but build API pulls for repeatable reports.
Google's v2 REST reference documents these paths relative to https://gmailpostmastertools.googleapis.com. Use the /v2 endpoints for the stable API; /v2beta is a separate version.
Useful v2 endpointsHTTP
GET /$discovery/rest?version=v2 GET /v2/domains GET /v2/{name=domains/*} GET /v2/{name=domains/*/complianceStatus} POST /v2/{parent=domains/*}/domainStats:query POST /v2/domainStats:batchQuery
What the v2 API can do
For most reporting use cases, the important v2 additions are date range queries, batch queries, and compliance status. A batch query reduces repetitive calls across multiple domains. A date range query lets an extract job request the reporting window it needs instead of looping through single-day calls.
|
|
|
|---|---|---|
Daily spam rate | SPAM_RATE | Data delay |
Authentication success | AUTH_SUCCESS_RATE | Requires an auth_type filter |
Delivery errors | DELIVERY_ERROR_RATE | Optional error_type and error_reason filters |
Many domains | Batch query | Normalize rows |
Compliance | getComplianceStatus | Check the domainId in each result |
Tableau | Extract table | Needs ETL |
Common v2 reporting jobs and metric filters.
Email traffic metrics also include TLS encryption rates and feedback loop spam rates. Google's metric definitions specify the filters: AUTH_SUCCESS_RATE selects spf, dkim or dmarc with auth_type; TLS_ENCRYPTION_RATE requires traffic_direction; FEEDBACK_LOOP_SPAM_RATE requires a feedback_loop_id. Include the metric filters in your warehouse model so different measurements do not share the same key.
Use the v2 API for both operational monitoring and executive reporting. Operations teams care about whether SPF, DKIM, and DMARC comply for active mail streams. Leadership often wants complaint trends and compliance posture. Keep source, domain, date, metric, and refresh time visible in both views.
The compliance response also includes unsubscribe verdicts and deliverability status. complianceData describes the registrable domain, while subdomainComplianceData is populated for a requested subdomain when its data is available. Preserve each domainId and keep these results separate when building reports.
Beyond statistics, v2 includes domain management and user access methods. These methods can add, verify, list, and remove domains, then manage which Google accounts can access each domain.
V1 pattern
- Stats: Traffic statistics were fetched with trafficStats calls.
- Dates: trafficStats.get fetched one day; trafficStats.list fetched multiple days.
- Migration: Old client code needs method and schema changes.
V2 pattern
- Stats: Domain statistics are fetched through query methods.
- Dates: Date ranges are supported for cleaner extract jobs.
- Scale: Batch queries reduce work across many domains.
How a v2 statistics request works
A raw REST request to domainStats:query must include metricDefinitions and timeQuery. aggregationGranularity is optional and defaults to DAILY; pageSize is also optional. Follow the current REST request schema rather than copying top-level startDate and endDate arguments from simplified migration examples. The custom name in each metric definition comes back in the response, so use stable names that map cleanly to warehouse columns.
Daily spam rate request bodyJSON
{ "metricDefinitions": [ { "name": "spam_rate", "baseMetric": { "standardMetric": "SPAM_RATE" } } ], "timeQuery": { "dateRanges": { "dateRanges": [ { "start": {"year": 2026, "month": 7, "day": 1}, "end": {"year": 2026, "month": 7, "day": 7} } ] } }, "aggregationGranularity": "DAILY", "pageSize": 200 }
The response contains domainStats plus nextPageToken. The default page size is 10 and the maximum is 200. Send nextPageToken as pageToken with the same query until the token is empty, even if a page contains fewer rows than requested. The API returns statistics only for dates where data is available.
Both dates in a date range are inclusive. In the response schema, each domainStats entry identifies a requested metric with its metric field. Use that field instead of parsing the opaque resource name, and read the value's typed field; intValue is an integer encoded as a string.
The read-only traffic scope supports statistics and compliance-status requests. For domain or user management, choose a scope authorized for that method, such as the broader postmaster scope.
OAuth 2.0 setup and domain access
Google's API setup instructions require OAuth 2.0 authorization by an authenticated user. Domain verification and OAuth consent are separate steps: the Google account authorizing the integration must also have access to the domain in Postmaster Tools.
- Enable the Postmaster Tools API in your Google Cloud project, configure the OAuth consent screen and create an OAuth client appropriate for the application.
- Authorize the integration with a Google account that owns the verified domain or has been granted access to it.
- For reporting jobs, request https://www.googleapis.com/auth/postmaster.traffic.readonly and attach the access token to API requests.
- For scheduled jobs, request offline access and securely store the refresh token so the job can obtain new access tokens without repeated interactive sign-in.
Headers for a JSON statistics requestHTTP
Authorization: Bearer ACCESS_TOKEN Content-Type: application/json
If a query returns PERMISSION_DENIED, check the authorizing account's domain access and OAuth scopes. Refresh expired access tokens; if consent has been revoked, authorize the integration again. Record authentication errors separately from successful queries with no statistics.
How to connect it to Tableau
The clean Tableau path is API pull, normalization, storage, then Tableau. Do not design this as a live dashboard that calls Google on every view. Postmaster data has reporting delays, OAuth access tokens expire, and retries belong in an extract job rather than inside a BI workbook.
Google Postmaster Tools API v2 workflow for domain verification, data storage and Tableau refreshes.
A basic implementation needs a verified authentication domain, a Google Cloud project, the Postmaster Tools API enabled, OAuth credentials, and a scheduled job. The authentication domain is the DKIM signing domain or the SPF Return-Path domain used to authenticate the mail.
Illustrative reporting extract (pseudocode)PYTHON
for domain in domains: stats = query_domain_stats(domain, start_date, end_date) rows = normalize_postmaster_stats(stats) warehouse.upsert(rows, keys=["domain", "date", "metric"]) tableau.refresh("gmail_postmaster_extract")
A storage table or extract lets the job retry failed pulls, control the schema, record refresh timestamps and reconcile API numbers with the Postmaster UI. Implement retry handling in the scheduled job.
Check authentication alongside reporting setup. A missing DMARC reporting address prevents aggregate reports from reaching that destination, but does not itself block Postmaster API access. Suped's domain health check checks DMARC, SPF, DKIM and related DNS details. Use a message test to confirm how an actual sender authenticates.
?
What's your domain score?
Deep-scan SPF, DKIM & DMARC records for email deliverability and security issues.
Data availability and reporting limits
Google's statistics guide says statistics are available only for domains that send mail to at least 50 Gmail users per day. Meeting that minimum does not guarantee every metric or date has data. Reporting delays and privacy thresholds still apply, so treating missing values as zero will mislead readers.
- No row: The API omits dates without available data, which is not the same as a zero spam rate.
- Volume: At least 50 Gmail users per day is a documented minimum, not a guarantee of complete reporting.
- Source: Postmaster reports on mail to personal Gmail accounts, not all mailbox providers or Google Workspace recipients.
- Migration: Old v1 dashboards need schema review before anyone trusts trend comparisons.
A zero reported spam complaint rate does not prove inbox placement. Google's dashboard documentation explains that the rate measures recipient spam reports on eligible inbox-delivered messages. If Gmail already sends many messages to spam, the reported rate can remain low. Keep spam rate separate from delivery errors and authentication success rates.
Google's support note says retirement of the legacy Postmaster Tools web interface has been postponed, with no new date announced. Google still directs senders to v2 and says the v1 API will be retired. The legacy Domain and IP Reputation dashboards will also be retired rather than carried into v2 unchanged. The web-interface postponement does not remove the requirement to migrate API clients.
Store the raw API payload, normalized metric rows, refresh timestamp, API version, domain, and date. This makes reconciliation possible when the UI, v1 exports, and v2 extracts do not match perfectly.
For a deeper comparison of old and new spam reporting, the related note on v1 versus v2 covers measurement differences in detail.
Where Suped fits
Google Postmaster Tools is one Gmail-specific input. Suped is our DMARC reporting and email authentication platform. It adds aggregate DMARC reports and authentication alerts for investigating sending sources alongside Postmaster data.
Suped DMARC dashboard showing email volume, authentication health, and source breakdown
A practical workflow uses Postmaster API data for Gmail complaint and compliance reporting, then uses Suped's DMARC monitoring to identify which sources are authenticated, which sources are failing, and what should be fixed next.
Postmaster Tools can show that Gmail spam rate increased. Use Suped to check for sender authentication failures or unapproved sending sources, then compare those findings with campaign and delivery logs. These checks do not establish why recipients reported spam. Suped's blocklist monitoring checks domain and IP blocklist (blacklist) listings alongside the Gmail-specific API signals.
For campaign-level checks, send a real message through Suped's email tester and inspect authentication, headers, DNS, and content signals before reviewing delayed Postmaster trends.
Implementation tips
Best practices
Check the v2 discovery document before changing extract jobs, data models, or dashboards.
Compare API and UI spam rates using the same domain, date range and metric definitions.
Store raw daily pulls so schema changes do not erase the ability to reconcile old reports.
Pair Postmaster data with DMARC reports and sending logs to investigate authentication failures.
Common pitfalls
Assuming the v1 trafficStats schema can be swapped to v2 without changing query logic.
Building Tableau reports directly on OAuth calls without a staging table or retry process.
Using Postmaster spam rate alone to decide whether authentication or content caused trouble.
Expecting domain and IP reputation dashboards to return unchanged in the v2 migration.
Expert tips
Build one normalized date table so Gmail metrics, DMARC results, and send logs line up.
Flag days with no Postmaster rows separately from days with a true zero complaint rate.
Requery a recent rolling date window to capture delayed data, then upsert the refreshed rows.
Keep a dashboard note explaining v1 and v2 schema differences and missing-data handling.
