Google Postmaster Tools: Setup and Dashboards Guide

What is Google Postmaster Tools?

Google Postmaster Tools is Google's free dashboard for senders, at postmaster.google.com, that reports how Gmail receives mail from your domain: user-reported spam rate, compliance with Gmail's sender requirements, SPF, DKIM, and DMARC pass rates, TLS encryption, delivery errors, and feedback-loop data per campaign. It only covers mail sent to personal Gmail accounts, meaning addresses ending in @gmail.com or @googlemail.com; Google Workspace business mailboxes are not included, and neither are Outlook.com or Yahoo recipients. Data is not real time: Google says dashboards are typically updated within 24 hours, use UTC, and may omit days when your volume is low to protect user privacy. Time ranges are 7, 30, 60, 90, or 120 days. Postmaster Tools is the only first-party view Gmail gives you, so if your users are mostly consumers on Gmail, it is the most important deliverability signal you have, and the one that tells you whether you are meeting the 0.30% spam rate ceiling in Google's email sender guidelines.

How do you add and verify a sending domain?

Setting up Postmaster Tools takes three steps and one DNS record. Step 1: sign in at postmaster.google.com with any Google account, click Add new domain, and enter the domain that authenticates your mail: the DKIM d= domain or the SPF Return-Path domain, not just the visible From domain. If you send through an email API on a subdomain such as mail.example.com, check which domain the DKIM signature actually uses in a received message's headers. Step 2: verify ownership by copying the TXT record (google-site-verification=...) or CNAME record Google shows into your DNS, then click Verify; Google says this is usually immediate and can take up to 10 minutes. Step 3: optionally grant teammates access. Once the primary domain is verified, you can add subdomains without verifying them again, and each subdomain gets its own dashboards. If more than one Google account needs access, each account needs its own verification record. Expect empty dashboards until Gmail has seen enough authenticated volume, often a few hundred messages a day.

; DNS TXT record on the root of the domain you added
example.com.  3600  IN  TXT  "google-site-verification=AbCdEf123..."

; confirm it is published
dig +short TXT example.com | grep google-site-verification

What do the Postmaster Tools dashboards show?

Google's help center documents eight dashboards. Compliance status shows whether you meet each sender requirement. Spam rate shows the share of your inboxed messages that recipients manually marked as spam. IP Reputation and Domain Reputation rate your sending IPs and domain as Bad, Low, Medium, or High, based on DKIM-authenticated mail (SPF-authenticated if you do not sign with DKIM). Feedback loop shows spam rates per campaign identifier from your Feedback-ID header. Authentication shows the percentage of traffic passing SPF, DKIM, and DMARC. Encryption shows the percentage of mail delivered over TLS. Delivery errors shows the percentage of authenticated messages Gmail rejected or temporarily deferred, with the error type. Since the move to the v2 interface, several deliverability vendors, including Warmy and Suped, report that the High/Medium/Low reputation labels were removed and replaced by compliance checks and plain-language deliverability verdicts. Google's own help page still documents the reputation dashboards, so what you see may depend on when your account moved to v2; read the dashboards your account actually shows.

How is the Postmaster Tools spam rate calculated?

The spam rate in Postmaster Tools is the percentage of your messages that were delivered to an engaged Gmail user's inbox and then manually marked as spam by that user. Mail that Gmail filtered to spam automatically is not in the numerator, and messages a user moves from spam to inbox count as inbox deliveries. That definition explains the most common misreading: a sudden drop to 0.0% after a high rate usually means Gmail is now sending most of your mail to spam, so nobody is left to click 'Report spam'. Google's guidelines set the hard limit at 0.30%; above it, mitigation is restricted. Deliverability practitioners such as Suped treat 0.10% as the working ceiling, 0.10% to 0.30% as a warning to pause broad sends, and anything above 0.30% as an incident. Read it as a trend against your send log: a spike on the day of a campaign, import, or new automation tells you exactly which stream caused it.

What does the Compliance status dashboard check?

The Compliance status dashboard checks your traffic against each requirement in Gmail's email sender guidelines and marks each one Compliant or Needs work. For all senders it checks SPF and DKIM authentication, DNS records (valid forward and reverse DNS for sending IPs), message formatting according to RFC 5322, TLS encryption, and the user-reported spam rate. For bulk senders, defined as roughly 5,000 or more messages to Gmail accounts in 24 hours, it adds DMARC authentication with alignment, one-click unsubscribe (RFC 8058 List-Unsubscribe-Post headers), and honoring unsubscribes. Two details trip people up. Status is reported for the primary domain only, even if you added a subdomain: data from email.example.com rolls into example.com. And like other dashboards, changes take up to 24 hours or more to show. A green compliance page means your setup is correct, not that recipients want your mail; vendors report that Google's newer deliverability verdicts can say users do not want your messages while every compliance check passes.

How do you use Feedback-ID with Postmaster Tools?

The Feedback-ID header lets the Feedback loop dashboard break your spam rate down by campaign, customer, or message type. Its format is Feedback-ID: a:b:c:SenderId, where SenderId is a mandatory, consistent identifier of 5 to 15 characters and a, b, and c are up to three optional identifiers. Gmail aggregates data per identifier, reading from the right. Three rules from Google's documentation matter. The message must be DKIM-signed by your own domain after the header is added, so the header cannot be spoofed, and that domain must be verified in Postmaster Tools. Identifiers must not be unique per message: never use a Message-ID, user ID, or timestamp, because no aggregate would ever reach the reporting threshold. And reports appear only for identifiers with enough volume and distinct spam reports on a given day, so a quiet stream shows nothing. With an email API that accepts custom headers, set the header on each send; for a multi-tenant SaaS, putting the customer ID in one field shows which customer's traffic generates complaints.

curl https://sendhq.cc/api/v1/emails \
  -H "Authorization: Bearer $SENDHQ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: digest-2026-10-01-u481" \
  -d '{
    "from": "Acme <updates@mail.acme.dev>",
    "to": ["user@gmail.com"],
    "subject": "Your weekly digest",
    "text": "...",
    "headers": { "Feedback-ID": "weekly-digest:cust-042:notify:acmemail" }
  }'

What does Postmaster Tools not tell you?

Postmaster Tools leaves four gaps you have to fill elsewhere. It covers only Gmail consumer mailboxes, so Microsoft Outlook.com, Yahoo, Apple iCloud, and corporate Google Workspace recipients need other sources: Microsoft SNDS for Outlook.com IP data, Yahoo's complaint feedback loop, and your DMARC aggregate reports (rua) for authentication across all receivers. It is aggregated and delayed by about a day, so it cannot stop a bad send in progress; per-message bounce and complaint events from your email provider can. It does not show inbox placement directly: messages in spam are counted as delivered in the delivery-errors view. And it hides low-volume days, so a new domain warming up may see nothing for weeks. A practical stack is Postmaster Tools for Gmail trends, DMARC reports for authentication coverage, and your provider's event stream for individual messages. With SendHQ, each message records queued, sent, delivered, bounced, complained, or failed, so you can match a spam-rate spike to the exact sends behind it.

Is there a Postmaster Tools API?

Yes. Google offers the Gmail Postmaster Tools API at gmailpostmastertools.googleapis.com. The original v1 API exposes domains and per-day trafficStats. The newer v2beta API adds domains.getComplianceStatus to read the compliance checklist programmatically, domains.domainStats for metrics, and domainStats:batchQuery to query several domains in one request, which matters for platforms that send on behalf of many customer domains. Access uses OAuth 2.0 as a Google account that has access to the verified domain in Postmaster Tools. Vendors report that Google planned to retire v1, so new integrations should target v2beta. A useful daily job pulls the spam rate and compliance status for each sending domain, writes them next to your own send volumes and complaint events, and alerts when the Gmail spam rate crosses 0.10% or any compliance item changes to Needs work. Because data lags about 24 hours, schedule the job once a day rather than polling.

Vragen die teams stellen

Primaire bronnen

• Set up Postmaster Tools — Google
• Postmaster Tools dashboards — Google
• Feedback loop (Feedback-ID) — Google
• Gmail Postmaster Tools API v2beta — Google
• Email sender guidelines — Google
• Google Postmaster Tools v2: What Changed After v1 Retired — Warmy