Why is my primary domain not compliant with Google one-click unsubscribe while the subdomain is?
Updated on 11 Oct 2026: We clarified primary-domain and subdomain reporting and added checks for RFC 8058 unsubscribe requests.
The apparent mismatch usually comes from comparing different reporting scopes. Google's Compliance status help describes a primary-domain result that includes subdomain traffic. Its current Postmaster Tools API also returns a separate subdomain result when data is available. A compliant subdomain can therefore coexist with a primary-domain Needs work result. Check the scope of each result before investigating the other marketing or subscribed streams under that primary domain. See Google's dashboard guidance and API documentation.
Treat this as an evidence problem. Google counts messages sent from the same primary domain toward the bulk-sender threshold, including messages from subdomains. Once the primary domain sends close to 5,000 messages to personal Gmail accounts in a 24-hour period, it meets Google's bulk-sender definition, and that classification does not expire. Start by finding marketing or subscribed mail without compliant one-click handling anywhere under that primary domain.
For background on the same reporting pattern, the root-domain compliance guide explains why Google Postmaster Tools can surface primary-domain issues when the sender expects subdomain-level reporting.
How Google rolls up compliance data
Google includes subdomain traffic when calculating the primary-domain result. In the current API, complianceData covers the registrable domain, such as example.com, while subdomainComplianceData covers the requested subdomain when available. Read the domain label on each result before treating a green subdomain as evidence that the whole primary domain complies.
Read the dashboard in the right scope
- Primary-domain result: The primary-domain result includes traffic from its subdomains; a separate subdomain result covers a narrower scope.
- Subdomain inputs: Promotional traffic from subdomains contributes to the primary-domain result.
- Personal Gmail only: The dashboard covers mail sent to personal Gmail accounts, not Google Workspace recipients.
- Rolling data: Low volume can produce No data found, and fixes can take up to seven days to appear.
This rollup explains why a compliant subdomain result or healthy message sample can coexist with a primary-domain warning. Another subdomain, campaign, or older message stream can still supply the non-compliant traffic used in the primary-domain calculation.
Why the primary domain shows Needs work
One-click unsubscribe compliance follows the promotional mail Google receives, and the Compliance status dashboard rolls that mail up to the primary domain. A clean message sample from one subdomain does not prove that every promotional stream under the primary domain complies.
Inspect every promotional stream
If the primary domain shows Needs work, inspect marketing and subscribed mail across the root domain and every subdomain. Common causes include a secondary campaign stream, bulk sales outreach, product announcements, lifecycle messages, or an older integration that lacks the required header pair. True personal and transactional messages do not require one-click unsubscribe.
Header details create further failure points. A sender can include a body link but omit List-Unsubscribe-Post, provide only a mailto option, or send the HTTPS request to a preference page instead of processing the unsubscribe directly. A platform change can remove the one-click header pair from one stream. DKIM can also pass without signing those two header fields.
Google Postmaster Tools showing one-click unsubscribe compliance for a primary domain and subdomain.
Known compliant stream
- Known sender: Campaign mail leaves through the expected platform.
- Good headers: List-Unsubscribe and List-Unsubscribe-Post are present.
- Stable DKIM: A passing DKIM signature covers both unsubscribe headers.
Primary-domain rollup
- Other stream: Another subdomain sends marketing or subscribed mail.
- Missing headers: That mail has no compliant one-click header pair.
- Spam reports: Recipients report messages without one-click unsubscribe as spam.
Google one-click unsubscribe requirements
For bulk senders, Google requires marketing and subscribed messages to support one-click unsubscribe and include a clearly visible unsubscribe link in the message body. The header requirement is separate from the body link. The body link can open a preference page, but the header HTTPS flow must process the unsubscribe directly.
A Needs work result does not mean Gmail automatically rejects a message only because one-click unsubscribe is missing. Google says bulk senders that miss this requirement are not eligible for delivery mitigation. Recipients are also more likely to report unwanted mail as spam when a simple opt-out is unavailable, which can damage later delivery.
Gmail's visible Unsubscribe button is not a compliance test. Google displays it only when a message passes its automated eligibility checks, even if the RFC 8058 headers are present. Inspect the received headers instead of relying on that button. Google's sender FAQ explains the distinction. The same primary-domain question appears in a Google community thread.
Compliant one-click unsubscribe headerstext
List-Unsubscribe: <https://u.example.com/o/123>, <mailto:u@example.com> List-Unsubscribe-Post: List-Unsubscribe=One-Click
RFC 8058 requires a valid DKIM signature covering both List-Unsubscribe and List-Unsubscribe-Post. Confirm that both names appear in the h= tag of the same passing signature. A DKIM pass that omits either field does not meet that requirement. See RFC 8058.
Partial DKIM-Signature example showing required header coveragetext
DKIM-Signature: d=example.com; s=s1; h=from:to:subject: list-unsubscribe:list-unsubscribe-post;
The List-Unsubscribe requirement is separate from DMARC. DMARC checks whether a matching authenticated domain supports the visible From identity. One-click unsubscribe gives Gmail a safe way to remove a recipient without relying on a body link.
How to read the signal
Use the Postmaster status to set the next action, then confirm it with message evidence.
Compliant
Monitor
Keep sampling promotional messages and watch for sending changes.
Needs work
Investigate
Inspect promotional streams across the primary domain and its subdomains.
No data found
Verify
Google lacks enough qualifying mail to calculate a status.
Common causes of one-click unsubscribe failures
When the primary-domain result fails while one known subdomain stream looks correct, start with a short list. Most cases come down to another promotional source, a header difference, or delayed suppression. Check which entry says Needs work: One-click unsubscribe concerns implementation, while Honor unsubscribe concerns processing requests within 48 hours.
|
|
|
|---|---|---|
Hidden campaign | Headers absent | Find owner |
Body-only opt-out | No POST header | Add RFC 8058 |
Spam-reported mail | One-click unsubscribe: Needs work | Check Feedback Loop |
DKIM gap | Headers unsigned | Update signing |
Slow suppression | Honor unsubscribe: Needs work | Remove in 48 hours |
Compact triage list for primary-domain one-click unsubscribe failures.
- Secondary campaigns: Another subdomain sends promotions outside the main campaign program.
- Corporate bulk mail: Teams send announcements, webinar invitations, or customer promotions through regular mailboxes.
- Sales outreach: Repeated commercial mail can require one-click handling when it functions as bulk promotional traffic.
- Support broadcasts: A support system sends product notices to lists instead of individual ticket replies.
- Old automations: Forgotten promotional and lifecycle messages keep running after a migration.
A bad list is another practical clue. If a quiet stream suddenly sends to stale or purchased recipients, Gmail can receive both more spam reports and more promotional messages without compliant one-click handling. That combination can move the primary-domain result to Needs work. Use the Postmaster Tools Feedback Loop to identify complaint-heavy campaigns. Add a campaign-level Feedback-ID before DKIM signing and verify the signing domain in Postmaster Tools. Missing Feedback Loop data does not prove there are no complaints; reporting depends on sufficient message and complaint volume. See Google's Feedback Loop guidance.
?
What's your domain score?
Deep-scan SPF, DKIM & DMARC records for email deliverability and security issues.
The domain health checker checks the public authentication posture before internal owners are contacted. Message samples are still needed for one-click unsubscribe because DNS alone cannot prove header compliance.
Identify the failing sending source
Use DMARC aggregate data first because it shows source IPs and authentication results for mail seen by reporting receivers. The reports do not contain List-Unsubscribe fields, but they narrow the investigation to real mail sources. Then send or capture samples from each promotional source and inspect the full headers.
Example for a domain without an existing DMARC recorddns
_dmarc.example.com TXT "v=DMARC1; p=none; rua=mailto:dmarc@example.com"
If the primary domain has no DMARC reporting, add it. If it already has a record, add or confirm the rua reporting address without weakening the existing policy. Confirm that reports are flowing and review sources for the root domain and its subdomains. A subdomain with its own DMARC record can use a different reporting destination, so include those reports in the investigation.
Suped DMARC dashboard showing email volume, authentication health, and source breakdown
Suped is our DMARC and email authentication platform. Suped's DMARC monitoring groups source IPs and authentication results with domain identities and sending volumes so teams can identify the traffic that needs message-level testing. DMARC aggregate reports do not contain unsubscribe headers or prove that an HTTPS unsubscribe request was processed.
What to pull from DMARC reports
- Source IP: Map the IP to the sending owner or platform.
- Header domain: Record the exact visible From domain for each source.
- Authentication result: Investigate failed authentication before deciding whether a source is unauthorized.
- Volume trend: Look for a new promotional source before the Postmaster status changed.
After that, test real messages. Send a sample through every promotional source under the primary domain to Gmail and inspect the full headers. In Gmail, open the menu beside Reply and choose Show original. Record the visible From domain, Return-Path, and DKIM d= domain so you can compare the identities behind each dashboard result. Suped's email tester helps confirm the exact header set, authentication outcome, visible From domain, and DKIM coverage without waiting for Postmaster data to refresh.
Email tester
Send a real email to this address. Suped shows a results button when the test is ready.
?/43tests passed
Test the HTTPS unsubscribe endpoint
The header pair alone does not prove the endpoint works. Use the exact HTTPS URL from a message sent to a test subscriber and send a POST with List-Unsubscribe=One-Click as the request body. A successful request must unsubscribe that recipient from the associated list without another user action. RFC 8058 defines the request behavior.
- Encode the recipient and list in the URL, preferably with a hard-to-forge token. The request must work without cookies, login, or HTTP authorization.
- Handle POST directly without an HTTPS redirect or confirmation page. Opening the URL with GET in a browser does not test this flow.
- Check firewall and bot-protection logs for blocked requests. Confirm receipt and suppression in the mailing system within 48 hours; an HTTP success response alone does not prove suppression.
- Give each subscription list a unique List-ID or From address, and confirm that the request removes the test subscriber from the list associated with the message.
If headers pass but Honor unsubscribe remains Needs work, investigate request handling and suppression synchronization. Google holds senders responsible for processing unsubscribe requests even when infrastructure blocks them. See its unsubscribe troubleshooting guidance.
Fix the failing sending stream
The fix depends on which source caused the status change. Do not change every DNS record at once. Find the stream, fix the stream, then watch the rolling result for up to seven days.
Steps to investigate Google one-click unsubscribe: map DMARC sources, inspect headers, and fix the sender.
- Find sources: Use DMARC aggregate reports to identify IPs and platforms using the primary domain or its subdomains.
- Classify mail: Separate personal and transactional mail from marketing and subscribed messages that require one-click unsubscribe.
- Add opt-outs: For qualifying mail, add the RFC 8058 header pair and a clearly visible unsubscribe link in the body.
- Check DKIM: Confirm DKIM passes and signs the unsubscribe headers. The DKIM checker validates the DNS selector record; verify the passing signature and its h= coverage in the received message.
- Process requests: Test the HTTPS POST flow and remove recipients from the associated mailing list within 48 hours.
- Retest samples: Send controlled messages to Gmail and confirm the exact headers before waiting on reporting.
If the mail is promotional
Fix the sender. Add compliant headers and a visible body link, make sure DKIM covers the header fields, and keep recurring bulk mail on an approved campaign identity.
- Owner: Assign the stream to a team.
- Header fix: Enable RFC 8058 handling.
- Retest: Confirm with a Gmail sample.
If the mail is unauthorized
Handle unauthorized mail as a separate authentication problem. Remove unauthorized SPF permissions and revoke compromised DKIM keys. After confirming legitimate sources authenticate correctly, use a DMARC enforcement policy to request quarantine or rejection of messages that fail DMARC.
- Policy: Verify legitimate sources before moving toward p=reject.
- SPF: Remove unused senders.
- DKIM: Rotate exposed keys.
If the primary domain should not send bulk mail, keep marketing and lifecycle streams on approved subdomains, keep the root for human mail, and require an owner for every automated stream. This makes future primary-domain warnings easier to trace. Moving mail to a subdomain does not remove it from the primary-domain bulk-sender count or compliance result.
