Google Postmaster Tools: The 2026 Guide to v2, Spam Rate and the API

Google Postmaster Tools is Gmail's free dashboard for bulk senders. It shows how Gmail sees mail from your domain: whether you meet Gmail's sender requirements, your user-reported spam rate, authentication pass rates, TLS encryption, delivery errors and feedback-loop data. In 2026 Google is moving senders toward Postmaster Tools v2 while the legacy web-interface deprecation remains postponed. The v2 API and v2 dashboards are the current path; Google says the Domain and IP Reputation dashboards are the exception slated for retirement.

This guide covers setup, the v2 dashboard model, what Google is retiring and why, the exact spam-rate thresholds, the API v2 changes, and how to monitor reputation signals when the v2 model does not expose the old reputation dashboards.

What Postmaster Tools is (and what it can't see)

Postmaster Tools reports on mail sent to personal Gmail accounts: addresses ending in @gmail.com or @googlemail.com. Google is explicit that the data covers only those accounts, and that its sender requirements and enforcement apply only to them.

That boundary matters more than most guides admit. If you sell B2B and your prospects use Google Workspace on their own company domains, those recipients never show up in Postmaster Tools. A cold email program can look quiet in Postmaster Tools even while filtering at those business domains changes. Use Postmaster Tools for Gmail consumer traffic and newsletters, and pair it with seed testing for business inboxes.

Three other rules shape what you'll see:

• Volume thresholds. To protect user privacy, dashboards may not show data on days when you send little mail to Gmail.
• Lag. Data is not real-time. Google says it typically updates within 24 hours but can take longer. All times are UTC.
• DKIM first. Some dashboards show only DKIM-authenticated mail, so you need DKIM signing with your own domain.

How to set up Google Postmaster Tools

Setup is quick if you can edit DNS.

1. Pick the right domain. Add the domain you authenticate with: the DKIM signing domain (d=) or the SPF Return-Path domain. If your ESP signs with its own domain, fix that first; Postmaster Tools can't attribute the mail to you.
2. Add it. Sign in at postmaster.google.com with a Google Account, go to Manage Domains, and click Add new domain.
3. Verify it. Open the domain's menu, choose Verify domain, and copy the TXT or CNAME record into your DNS. Google says verification is usually immediate but can take up to 10 minutes. Until you verify, no data appears.
4. Add subdomains (optional). Add news.example.com or mail.example.com separately if you want their data split out. Once the parent domain is verified, subdomains don't need their own verification.
5. Share access. Under Manage users, add colleagues by Google email address. Postmaster Tools does not notify them, so tell them yourself.
6. Set up the feedback loop. Add a Feedback-ID: a:b:c:SenderId header to your mail. SenderId is required (5 to 15 characters, consistent across the stream); up to three optional identifiers can mark campaign, customer or mail type. The mail must be DKIM-signed by a domain you verified in Postmaster Tools.

To keep multiple Google accounts with access to the same domain, give each account its own DNS verification record.

What Postmaster Tools v2 shows

Pick a verified domain, a dashboard and a time range (7, 30, 60, 90 or 120 days).

Compliance status

This dashboard maps directly to Gmail's sender guidelines. For all senders it checks the required SPF-or-DKIM authentication path, DNS records (forward and reverse DNS), message formatting, encryption and the user-reported spam rate. For bulk senders (about 5,000 or more messages to Gmail accounts in 24 hours) it adds SPF and DKIM authentication together with DMARC, one-click unsubscribe and honoring unsubscribes.

Each line reads Compliant, Needs work or No data found. Three details catch people out:

• It reports on the primary domain only, using data from its subdomains. Add email.example.com and you'll see compliance for all of example.com.
• DNS status reflects your records when the mail arrived, not now. Use the Google Admin Toolbox to check current DNS.
• After a fix, Google says it can take up to 7 days to show, because the dashboard uses a rolling average.

"Honor unsubscribe" shows Needs work if you don't process requests within 48 hours. Google counts a request as made even if something like a CDN or WAF blocked it before it reached your server, so check that your unsubscribe endpoint is reachable.

Spam rate

The spam rate is the share of messages delivered to the inbox that recipients then reported as spam. Mail that went to spam and was then marked "not spam" counts as inbox-delivered.

The catch: if Gmail already sends much of your mail to spam, fewer people see it in the inbox, so fewer can report it. A very low or suddenly zero spam rate can mean trouble, not success. Google's own troubleshooting names this case: a high rate that "suddenly changed to a rate of 0" often means messages are being filtered to spam automatically.

Feedback loop

The feedback loop dashboard shows the average spam rate across all your Feedback-ID identifiers and how many identifiers were active. Click a day to see individual campaigns. Identifiers appear only once they collect a minimum number of spam reports, so a missing ID usually means low complaints or low volume. A dropdown switches between From header domain (mail where your domain is the From: domain) and All signed domains (mail where your domain is one of the DKIM signers).

Delivery errors

This shows the share of authenticated mail that Gmail rejected or temporarily deferred. The reasons are the most useful part. Google's v2 API lists these rejection reasons: bad attachment, bad or missing PTR record, IP in RBLs, low domain reputation, low IP reputation, spammy content, stamp policy error and other. Temporary failures are split into anomalous traffic pattern and other.

Deliverability analysis

Under Compliance status, the Deliverability analysis gives a one-line verdict on your domain's standing with Gmail. The API exposes the reasons behind it:

This is the closest thing Gmail now offers to the old reputation color. Note that three of the seven reasons are about recipient behavior, not configuration.

What Google is retiring from Postmaster Tools, and why

Google's deprecation notice says the Domain and IP Reputation dashboards are not carried into v2 and are slated for retirement. Do not treat an older help article that still lists them as a promise that they will remain available.

The timeline:

• 2024: Google introduced the v2 experience and its Compliance status dashboard alongside the legacy interface.
• September 2025: Google announced September 30, 2025 as the then-planned legacy-interface retirement date. Treat that as a historical announcement, not the current deadline.
• Later in 2025: Google postponed the legacy web-interface deprecation after sender feedback. The current notice says v1 will eventually be retired, but it does not publish a replacement final date.
• December 2, 2025: the v2 API entered developer preview (v2beta).
• February 3, 2026: the v2 API became generally available. Google says it covers v1 functionality except Domain and IP reputation, and that the v1 API will be retired.
• June 24, 2026: domain and user-management methods and the compliance-status verdict became generally available in v2.

Google's stated reasons for dropping the reputation dashboard:

Google's stated rationale is that a reputation view is less actionable than the underlying sender signals, changes in behavior take time to appear, and reputation is only one input into delivery. Treat those as reasons to use the current compliance, spam-rate, delivery-error and engagement signals together, not as evidence that reputation is irrelevant.

The practical reading: Gmail still evaluates your domain and IP (that's why "low domain reputation" is still a rejection reason). The v2 model points senders at inputs they can change: complaints, compliance and engagement, rather than exposing the old reputation score dashboards.

Google's dashboard help and deprecation notice should be read together: the help page documents available dashboard types, while the deprecation notice identifies the reputation dashboards as the exception and says the legacy interface will eventually retire.

The 0.1% and 0.3% spam rate thresholds

These two numbers come straight from Google's guidelines and FAQ.

The impact is graduated, not a cliff at 0.3%. Spam rate is calculated daily. And improvements take time to change classification, so one clean week won't undo a bad month.

To put 0.1% in perspective: that's 1 complaint per 1,000 messages that reached the inbox. On a 50,000-message Gmail send, 50 complaints put you at the line.

Gmail isn't alone. Yahoo also requires bulk senders to keep complaints below 0.3%, and calculates the rate on inbox-delivered mail too.

Postmaster Tools API v2: what changed

If you pulled Postmaster data into a warehouse or monitoring tool with the v1 API, you need to migrate.

In v2 you request named metrics. The standard ones are SPAM_RATE, AUTH_SUCCESS_RATE (filter by spf, dkim or dmarc), TLS_ENCRYPTION_RATE and TLS_ENCRYPTION_MESSAGE_COUNT, DELIVERY_ERROR_RATE and DELIVERY_ERROR_COUNT (filter by error type and reason), and FEEDBACK_LOOP_ID and FEEDBACK_LOOP_SPAM_RATE. Both OAuth scopes still work: https://www.googleapis.com/auth/postmaster and postmaster.traffic.readonly.

getComplianceStatus returns data for the registrable domain and, when you query a subdomain, a separate block for that subdomain when data exists.

Migration is mostly mechanical: update the client library, swap trafficStats calls for domainStats.query, and rebuild any dashboard panels that charted reputation. For those panels, chart DELIVERY_ERROR_RATE filtered to low_domain_reputation and low_ip_reputation instead. It's the closest API signal to the old chart.

How to monitor sender reputation now

Losing the reputation chart hurts most when you're diagnosing a drop. Think of the old chart as a smoke alarm: it didn't tell you where the fire was, but you knew to look. You now need several smaller detectors instead:

1. Gmail spam rate and feedback loop. Your earliest warning. Alert at 0.1%, not 0.3%.
2. Delivery errors with reasons. A rise in low_domain_reputation rejects is the old red chart in a new form.
3. The Deliverability analysis verdict. Check it weekly and after any big send.
4. Public reputation signals. Use the live Folderly domain reputation checker for the DNS and other signals it currently exposes. Treat any unavailable licensed blocklist feed as unknown, not clear.
5. Blocklists. A listing can affect every mailbox provider that uses it. Check the relevant provider and blocklist documentation before requesting removal.
6. Other mailbox providers. Microsoft SNDS covers IPs you control at Outlook.com, and Yahoo's Complaint Feedback Loop reports complaints for DKIM-signed mail.
7. DMARC aggregate reports. They show participating receivers' observed traffic for your domain and whether it aligns; they are not complete coverage of every sender. Start with the DMARC checker.
8. Seed-based placement tests. One practical way to see where business inboxes put your mail, since Postmaster Tools skips Workspace recipients.

Common Postmaster Tools problems

When Postmaster Tools won't help

• B2B cold email to business domains. Workspace and Microsoft 365 recipients aren't in the data. Watch reply rates, bounce codes and seed placement.
• Low volume. Google may withhold data on low-volume days. Confirm the verified domain, DKIM signer and Gmail recipient volume before treating a blank dashboard as a fault.
• Brand-new domains. There's no history to show yet. Warm them gradually and validate placement with a controlled test.
• Diagnosing content. Postmaster Tools tells you that complaints rose, not which line of copy caused it. Use Feedback-ID to narrow it to a campaign.

FAQ

Is Google Postmaster Tools free?

Yes. Google does not charge for Postmaster Tools or its API. You need a Google Account or Google Workspace account and control of the DNS for the domain you want to monitor, because verification works through a TXT or CNAME record. The real constraint is volume: dashboards stay empty on days when you send too little mail to personal Gmail accounts.

Why does Google Postmaster Tools show no data?

Usually one of four reasons. You send too little to personal Gmail accounts on that day, since Google withholds low-volume data for privacy. You added the From: domain but authenticate with a different DKIM or Return-Path domain. The domain is not verified yet. Or your mail goes to Google Workspace business addresses, which Postmaster Tools does not cover. Data also lags by about a day.

Where did domain reputation go in Google Postmaster Tools?

Google's current deprecation notice says the Domain and IP Reputation dashboards are the exception not carried into v2 and are slated for retirement. It also says the legacy web interface deprecation was postponed and v1 will eventually retire. Use spam rate, compliance, delivery-error reasons and the Deliverability analysis verdict as the current Google signals.

What spam rate is too high for Gmail?

Google tells senders to keep the user-reported spam rate below 0.10% and never reach 0.30%. Above 0.1% already hurts inbox placement for bulk senders. At 0.3% or higher, bulk senders lose eligibility for delivery mitigation until the rate stays under 0.3% for 7 consecutive days. The rate counts only messages that reached the inbox, so a low number can hide a spam-folder problem.

What is the Microsoft equivalent of Google Postmaster Tools?

Microsoft's Smart Network Data Services (SNDS) is the closest match for Outlook.com, Hotmail and Live mailboxes. It is organized by sending IP rather than domain, so you request access to IP addresses for which you are responsible. It also provides the Junk Mail Reporting Program.

Does Postmaster Tools show data for Google Workspace recipients?

No. Google states that Postmaster Tools data applies only to messages sent to personal Gmail accounts ending in gmail.com or googlemail.com, and its sender requirements and enforcement apply to those accounts only. For B2B senders whose prospects use Workspace on their own domains, most of the audience is invisible in Postmaster Tools. Seed testing and reply-rate trends fill that gap.

How long does Postmaster Tools take to update after I fix something?

Most dashboards refresh within about 24 hours, but can take longer. The Compliance status dashboard uses a rolling multi-day average, and Google says fixes can take up to 7 days to show there. Spam rate improvements also take time to change how Gmail classifies your mail, so a clean week of data does not mean placement recovers the same week.

See what Postmaster Tools can't

Postmaster Tools covers one mailbox provider's consumer inboxes. For a separate domain-level view, use Folderly's live domain reputation checker and DMARC checker.

Last reviewed: September 28, 2026