Google Postmaster Tools is the closest thing to ground truth on how Gmail treats your sending domain. In 2026 the interface has changed shape twice: v1 was retired at the end of 2025, the v2 API went generally available in February, and June brought a Deliverability Analysis section that gives you a plain-English verdict on whether Gmail users want your mail. This guide covers what v2 shows today, what disappeared, how to set it up, how to call the API, and how to fix the issues senders hit most often.
What is new in 2026
- v1 dashboards and API are gone; the standalone Domain Reputation and IP Reputation panels no longer exist.
- API v2 became generally available on February 3, 2026, with queryDomainStats and batch operations.
- June 2026 added a Deliverability Analysis section with seven verdicts plus a technical fallback.
- High, Medium, and Low reputation scores are no longer surfaced; engagement and compliance signals took their place.
Timeline from v1 sunset to Deliverability Analysis
The transition happened in six checkpoints across roughly eighteen months. Any monitoring stack still hitting v1 endpoints in July 2026 is reading zeros.
| Date | Event | Impact |
|---|---|---|
| 2024 | Postmaster Tools v2 launched alongside v1 | Redesigned UI, Compliance Status introduced, both interfaces available in parallel |
| September 30, 2025 | v1 dashboard officially retired | UI access to v1 removed; all users forced onto v2 |
| October 31, 2025 | v1 API decommissioned | All v1 API calls return empty or error; integrations must migrate |
| December 2, 2025 | v2beta API developer preview | Full v2 dataset including Compliance Status accessible programmatically |
| February 3, 2026 | v2 API generally available | queryDomainStats, batch operations, domain and user management via API |
| June 2026 | Deliverability Analysis added to Compliance Status | Seven deliverability verdicts plus REASON_UNSPECIFIED surface user-intent signals directly |
Heads up: if your monitoring stack still calls v1 endpoints or scrapes the v1 dashboards, it has been returning empty data since October 31, 2025. The v2 API is not a drop-in replacement; the schema changed, and the reputation buckets it used to return no longer exist as fields.
What Postmaster Tools v2 shows today
The v2 dashboard consolidates everything into a single Compliance Status page with subsections. Here is what each metric measures and where healthy senders should sit.
| Metric | What it measures | Healthy threshold | Where to act |
|---|---|---|---|
| Compliance Status | Whether your setup passes Google’s bulk sender requirements | All green checks | Authentication records and one-click unsubscribe setup |
| Deliverability Analysis | Whether Gmail users want your mail, as a verdict | USERS_WANT_MAIL | List hygiene, engagement segmentation, sunset policy |
| Spam Rate | User-reported spam divided by delivered volume | Below 0.1%, alert line at 0.3% | List sourcing, content, frequency, opt-in path |
| Authentication | SPF, DKIM, DMARC pass and alignment rates | 99%+ pass on all three | DNS records, DKIM key alignment with visible From |
| Encryption | Share of traffic delivered over TLS | 99%+ TLS | MTA configuration, MTA-STS policy |
| Delivery Errors | Reasons Gmail rejected or deferred your mail | Below 1% errors | Volume ramp, IP reputation, content flags |
| Feedback Loop | Aggregated complaint data grouped by Feedback-ID header | Same 0.1% target as Spam Rate | Segment-level suppression via Feedback-ID |
What is gone: the standalone Domain Reputation and IP Reputation dashboards, the High / Medium / Low / Bad reputation buckets, and the v1 API endpoints. Google’s framing was explicit: static reputation labels are no longer how Gmail wants senders to think about deliverability. Engagement signals do the work those labels used to do, and the June 2026 Deliverability Analysis section is where they surface.
The Deliverability Analysis verdicts
The June 2026 update is the most consequential addition since v2 launched. Instead of leaving you to guess what a 0.2 percent spam rate means for placement, Google now states a verdict in plain English. The v2beta API reference exposes seven deliverability states plus REASON_UNSPECIFIED as a technical fallback, and they group into three buckets: users want your mail, Gmail sees no clear signal, or users signal they do not want it.
| Verdict | Bucket | What it means | Recommended action |
|---|---|---|---|
| USERS_WANT_MAIL | Wanted | Recipient engagement signals are strong across your Gmail audience | Protect the position: tight list hygiene, no cold additions |
| SOMEWHAT_USERS_WANT_MAIL | Wanted (soft) | Signals are positive but not decisive | Reinforce top-of-list engagement, tighten sunset policy |
| NO_CLEAR_SIGNAL | No signal | Insufficient engagement data to decide either way | Increase volume gradually, prioritize known engaged recipients |
| USERS_DIVIDED | No signal | Recipient behavior splits across your Gmail audience | Segment by engagement tier and treat cohorts differently |
| SOMEWHAT_USERS_DONT_WANT_MAIL | Not wanted (soft) | Signals are trending negative | Freeze the least engaged 30-day cohort, review acquisition sources |
| USERS_DONT_WANT_MAIL | Not wanted | Recipient behavior indicates the mail is not welcome | Halt sends to unengaged segments, run the recovery playbook |
| ABUSE_OR_SPAM | Not wanted | Content or behavior flagged as abusive or spammy | Immediate review of content, sending patterns, list sourcing |
| REASON_UNSPECIFIED | Technical fallback | API returned no verdict, typically low volume or new domain | Wait, keep sending consistently, re-check weekly |
If you see USERS_WANT_MAIL: your engagement signals are strong. Protect what you have. Keep list hygiene tight, do not add unengaged segments, and pre-validate any new acquisition source with SMTPing before you touch the list.
If you see USERS_DONT_WANT_MAIL: Gmail is telling you that recipient behavior (deletes without opening, spam complaints, low interaction) has crossed the threshold where placement is at risk. The cold IP recovery playbook applies. Freezing sends to unengaged segments and rebuilding around your 30-day openers is the standard first move.
What was retired and why
The retirement was not cosmetic. Google removed the reputation buckets because they were routinely misinterpreted, and because static labels tend to lag actual sending behavior by weeks.
| Feature | v1 (pre-Oct 2025) | v2 (2026) |
|---|---|---|
| Domain Reputation dashboard | Standalone panel with High/Medium/Low/Bad | Retired |
| IP Reputation dashboard | Standalone panel with same buckets | Retired |
| Reputation scoring model | Static labels | Removed; engagement and compliance signals only |
| Compliance Status | Not present | Central page covering authentication, spam rate, one-click unsub, delivery errors |
| Deliverability Analysis | Not present | Added June 2026: seven verdicts on user intent |
| Spam Rate | Available | Available |
| Authentication view | Available | Available and integrated into Compliance Status |
| Encryption view | Available | Available |
| Delivery Errors | Available | Available |
| Feedback Loop | Available | Available, keyed by Feedback-ID header |
| API | v1, get/list pattern | v2 GA February 2026: queryDomainStats, batch, domain/user management |
Portability angle: engagement signals travel with your sending domain, which is why the June update centers on user intent rather than an aggregate score. Two senders can hit the same 0.15 percent spam rate and get different verdicts depending on how their recipients actually interact with the mail.
How to set up Google Postmaster Tools
Setup takes about ten minutes plus DNS propagation.
1. Sign in at postmaster.google.com
Use the Google account that will own the domain. For team access, add other users after verification, either from the interface or via the API.
2. Add your sending domain
Click the plus icon and enter your root domain (example.com, not mail.example.com). Postmaster Tools tracks the root and its subdomains together for most metrics.
3. Verify with the TXT record
Google gives you a verification token to add as a DNS TXT record at the root:
example.com. IN TXT "google-site-verification=abc123XYZ..."Publish and wait for propagation. Verification usually resolves within an hour on managed DNS. Once the record is live, click Verify in the Postmaster Tools UI.
4. Wait for data
Postmaster Tools needs sustained volume before it displays anything. Under a few hundred messages a day to Gmail, most panels stay empty. This is the single most common cause of a no-data state and it is not a bug.
5. Manage users and multi-domain via the API
Since February 2026, the v2 API supports programmatic add, verify, and remove for domains and users. Multi-brand senders and agencies should script this rather than clicking through the UI for each property. See the API section below.
The Postmaster Tools v2 API
API v2 general availability landed on February 3, 2026. It replaces v1 completely; v1 was decommissioned alongside the dashboard on October 31, 2025.
What v2 brings that v1 did not: flexible date-range querying via queryDomainStats, batch operations across many domains, and the Deliverability Analysis verdict field on GetDomainComplianceStatus. The v1 rows-array response format is gone; responses are now typed objects.
What changed vs v1
- The v1 base URL and paths are gone. All calls now go through the v2 endpoints under gmailpostmastertools.googleapis.com.
- queryDomainStats replaces the paginated get and list pattern of v1 with flexible querying, including date ranges and specific metric subsets.
- Batch operations let you fetch stats for many domains in one call, which matters for agencies and platforms with many client domains.
- GetDomainComplianceStatus now returns the Deliverability Analysis verdict, the same one shown in the June UI update.
- Domain and user management (add, verify, remove, update permissions) moved from console-only to full API coverage.
Python example: read compliance and deliverability status
from googleapiclient.discovery import build
from google.oauth2 import service_account
SCOPES = ["https://www.googleapis.com/auth/postmaster.readonly"]
creds = service_account.Credentials.from_service_account_file(
"service-account.json", scopes=SCOPES
)
service = build("gmailpostmastertools", "v2", credentials=creds)
resp = service.domains().getComplianceStatus(
name="domains/example.com"
).execute()
print("Compliance:", resp.get("complianceStatus"))
print("Deliverability:", resp.get("deliverabilityStatus"))
Migration checklist v1 to v2
- Replace v1 base URL and paths with the v2 equivalents.
- Update auth scopes if you were using the older postmaster scope names.
- Adapt to the new schema: v2 returns typed objects rather than the v1 rows array in many endpoints.
- Switch reputation reads to the new Compliance Status and Deliverability verdict fields; the old reputation buckets no longer exist as returned values.
- Add error handling for REASON_UNSPECIFIED and empty responses on low-volume domains.
- If you built alerting on High to Medium transitions, rebuild it on Deliverability Analysis bucket changes instead.
How Postmaster Tools ties into the bulk sender rules
Since February 2024, senders above 5,000 messages per day to Gmail or Yahoo consumer addresses have had to pass three gates: aligned authentication (SPF and DKIM with DMARC), a spam complaint rate under 0.3 percent, and a working one-click unsubscribe. Postmaster Tools is where Google shows you whether you clear those gates.
- Authentication status confirms SPF and DKIM alignment plus DMARC policy.
- Spam Rate is the exact metric measured against the 0.3 percent alert line.
- Compliance Status calls out failures against the bulk sender requirements directly, including missing List-Unsubscribe headers.
See the list-unsubscribe header setup guide for the one-click implementation, suppression lists for the cleanup side, and the twelve reasons your emails go to spam if you are already over 0.3 percent and need to rank the fixes.
Practical note: Gmail applies the 0.3 percent threshold as an alerting line. Sustained rates above 0.1 percent are already a warning that placement is drifting. Do not wait for the alert to fire before acting.
Complementary tools and alternatives
Google Postmaster Tools only sees Gmail traffic. For a full deliverability picture, pair it with the equivalents at the other major receivers.
For the complaint reporting side across all receivers, including ARF parsing and per-provider signup, see the Feedback Loops and ARF guide.
Common issues and how to fix them
No data on every panel
The most common cause is volume below the display threshold. Postmaster Tools needs sustained volume to Gmail (roughly hundreds of messages a day, minimum) before it shows anything. If your warmup schedule is still in early ramp, this is expected. Cross-check your daily volume against target with the warmup calculator.
Verification TXT record is ignored
Check the record is at the root, not on a subdomain. Some DNS panels wrap TXT values in extra quotes, which breaks the match. Wildcards do not cover verification. If your DNS provider is slow to propagate, allow twenty-four hours before troubleshooting further.
Domain ownership lost after admin turnover
Re-verify from any Google account by re-adding the domain and publishing a fresh TXT record. Previous verifications persist but only tied to the original account, so account handoff is worth doing on purpose rather than after the fact.
DKIM d= alignment fails
Your SPF might align while your DKIM d= domain does not match the visible From address. Postmaster Tools flags this under Authentication. The fix is on the sending platform side: use a DKIM key signed with your root domain, not the ESP subdomain, so DMARC alignment passes.
Empty Feedback Loop tab
Google’s Feedback Loop uses the Feedback-ID header. If your ESP does not set one, or sets a static value across all campaigns, the tab stays empty because Google cannot group complaints. See the FBL and ARF guide for the header format and per-campaign strategy.
Deliverability Analysis stuck on NO_CLEAR_SIGNAL
This is a low-volume verdict. Gmail does not have enough recipient interactions to say either way. Ramp volume gradually and expect the verdict to shift within a few weeks of consistent sending. Adding volume in the form of unengaged recipients will not help; it may push you into a worse verdict.
Five common mistakes senders make with Postmaster Tools
The tool is only as useful as how you read it. These five patterns cost more than the metrics themselves.
Frequently asked questions
What is the minimum volume to see data in Postmaster Tools?
Google does not publish an exact number, but a few hundred messages a day to Gmail is the practical floor for most panels. Compliance Status and Authentication tend to populate faster than Spam Rate or Deliverability Analysis, which need engagement signals to compute.
Is Google Postmaster Tools free?
Yes. Both the dashboard and the API are free. You need a Google account and DNS control over the domain you want to monitor.
Does Postmaster Tools still show reputation scores?
No. The High, Medium, Low, and Bad reputation labels for domain and IP were retired with v1 in October 2025. Compliance Status and the Deliverability Analysis verdicts (added June 2026) replaced them.
What happened to the v1 API?
It was decommissioned on October 31, 2025, alongside the v1 dashboard. Any integration still calling v1 endpoints returns empty or errors. Migrate to v2, which went generally available February 3, 2026.
Can I use Postmaster Tools for cold outreach?
Only if your cold volume to Gmail crosses the display threshold, which is unlikely for typical cold campaigns (dozens to low hundreds per day). Even then, Postmaster Tools shows you the receiving side of what you already know: high complaint rates and low engagement. Pre-validation with SMTPing catches most of the underlying causes before they hit your metrics.
How often is the data updated?
Most metrics refresh daily with a one to two day lag. Compliance Status updates faster; the Deliverability Analysis verdict updates as recipient engagement signals accumulate, which means a change in behavior can take a week or more to reflect.
What is the difference between Compliance Status and Deliverability Analysis?
Compliance Status is a checklist: does your setup pass the bulk sender rules (authentication, spam rate, one-click unsubscribe)? Deliverability Analysis is a verdict: do Gmail users actually want your mail? You can pass compliance and still receive USERS_DONT_WANT_MAIL, and that is exactly when the deliverability picture matters most.
Where to go next
Postmaster Tools is the closest thing to ground truth on Gmail inbox placement, but it only covers Gmail. For a full picture, pair it with the receiver-side tools at Microsoft and Yahoo and with the complaint reporting side of the FBL hub.
- Feedback Loops (FBL) and ARF: signup, parsing, and suppression
- List-Unsubscribe and one-click headers setup
- Domain reputation vs IP reputation in 2026
- IP warmup schedule that works in 2026
- Cold IP recovery playbook
Historical timeline of Google Postmaster Tools updates
- June 2026: Deliverability Analysis section added to Compliance Status. Introduces seven deliverability verdicts (USERS_WANT_MAIL, SOMEWHAT_USERS_WANT_MAIL, NO_CLEAR_SIGNAL, USERS_DIVIDED, SOMEWHAT_USERS_DONT_WANT_MAIL, USERS_DONT_WANT_MAIL, ABUSE_OR_SPAM) plus REASON_UNSPECIFIED technical fallback.
- February 3, 2026: Postmaster Tools API v2 generally available. Adds queryDomainStats with date-range filtering, batch operations across many domains, and GetDomainComplianceStatus returning the deliverability verdict.
- December 2, 2025: v2beta API developer preview released with full Postmaster Tools dataset including Compliance Status data.
- October 31, 2025: v1 API decommissioned. All v1 endpoints return empty or error responses. Integrations built on the rows-array pattern must migrate.
- September 30, 2025: v1 dashboard officially retired. Legacy interface redirects to v2. Domain Reputation and IP Reputation panels removed; High, Medium, Low, and Bad reputation buckets no longer surfaced.
- 2024: Postmaster Tools v2 launched alongside v1. Redesigned interface, Compliance Status page introduced, both interfaces available in parallel during the transition period.
- February 1, 2024: Google and Yahoo unified bulk sender requirements enter enforcement. Postmaster Tools becomes the primary sender-facing surface for compliance visibility: SPF, DKIM, DMARC alignment, spam rate under 0.3 percent, and one-click unsubscribe on promotional mail above 5,000 messages per day.
- 2015: Google Postmaster Tools initially launched at postmaster.google.com. Original panels: Spam Rate, Domain Reputation, IP Reputation, Feedback Loop, Authentication, Encryption, Delivery Errors.
Pre-flight validation with SMTPing: catch disposables, role addresses, catch-alls, syntax errors, dead mailboxes, and known spam traps before they hit your Postmaster Tools spam rate. Thirteen validation types, twenty-five free checks daily, no card required. Try SMTPing free.
About the Author
Alaa · LinkedIn
Email infrastructure specialist with 8+ years of hands-on experience in SMTP, deliverability, and email verification. I’ve configured and troubleshot mail systems across Postfix, Exchange, and cloud relays, managed IP reputation and warmup campaigns, and built verification pipelines processing millions of addresses. My work spans DNS authentication (SPF, DKIM, DMARC, BIMI), bounce handling, blocklist monitoring, and compliance frameworks including CAN-SPAM and GDPR. I write every article on SMTPedia to give email professionals, developers, and marketers the accurate, RFC-grounded reference they need.
About SMTPedia
SMTPedia is an independent email industry reference covering SMTP, IMAP, POP3, email deliverability, marketing platforms, DNS authentication, and email verification. Every article is researched from official provider documentation, IETF RFCs, and industry best practices. Settings and configurations are verified quarterly.
We are cited as a source by ChatGPT, Microsoft Copilot, and thousands of email professionals worldwide. Learn more about our editorial process.
