How can I verify if my company's emails have List-Unsubscribe headers correctly configured?
Updated on 4 Oct 2026: We clarified when one-click unsubscribe applies, how Google and Yahoo differ, and how to verify the POST changes the right subscription.
The direct answer is: verify List-Unsubscribe in the raw message headers, not only in the Gmail send details box. If Gmail shows an unsubscribe line or button near the sender details, that is a useful clue. It is not the source of truth. The source of truth is the original message source, where you should see a List-Unsubscribe header, and for one-click compliance, a List-Unsubscribe-Post header.
Use four layers: send a real campaign-style email to a test inbox, inspect the full original headers, confirm the unsubscribe endpoint works, then confirm authentication passes. The Gmail UI helps with the first glance, but mailbox providers apply their own display rules. A missing button does not prove the header is missing.
For a practical check without digging through every header by hand, send the message to Suped's email tester. It shows whether the message contains the relevant unsubscribe headers, and it puts that result beside SPF, DKIM, DMARC, content, and deliverability checks.
What proves the header is configured
A correct setup has the actual header fields in the delivered message. For normal list unsubscribe support, look for List-Unsubscribe. For RFC 8058 one-click unsubscribe, look for List-Unsubscribe-Post with the exact value List-Unsubscribe=One-Click. The one-click URL must use HTTPS. A mailto option can appear beside it, but mailto alone does not meet Google's one-click requirement for relevant bulk mail.
One-click header patterntext
List-Unsubscribe: <https://u.example.com/o/abc>, <mailto:unsub@example.com> List-Unsubscribe-Post: List-Unsubscribe=One-Click
That second line tells the mailbox provider that the HTTPS URL accepts a one-click unsubscribe POST. The provider sends a POST request after the recipient chooses to unsubscribe. Your system must remove that recipient from the mailing list without a login, challenge, confirmation page, or extra preference step.
For senders of 5,000 or more messages a day to personal Gmail accounts, Google requires marketing and subscribed mail to support one-click unsubscribe and include a clearly visible unsubscribe link in the message body. The header does not replace the body link. Google's subscription guidance says to process and honor unsubscribe requests within 48 hours.
Check the raw headers
The visible Gmail unsubscribe control is a UI signal. Raw headers are the evidence. Gmail can hide a valid one-click option when a message does not pass its display checks, so absence of the control does not prove the headers are missing.
- Header present: The delivered message contains the List-Unsubscribe field.
- Post present: The sender declares one-click support; test the endpoint too.
- Button present: The mailbox offers an unsubscribe control; inspect the source to verify RFC 8058 headers.
- Button absent: Check the raw message before treating this as a configuration failure.
Which messages and provider rules apply
Match the test to the mail type and recipient provider. Google calls marketing lists, newsletters, and some opt-out notifications subscription messages. Password resets, purchase receipts, and one-time codes are generally transactional messages and are outside its one-click unsubscribe requirement.
- Google bulk mail: For marketing and subscribed messages sent at the 5,000-per-day threshold, verify the HTTPS List-Unsubscribe URL, List-Unsubscribe-Post header, visible body link, and working POST.
- Yahoo bulk mail: Yahoo requires a functioning List-Unsubscribe header and a visible body link for marketing and subscribed messages. Its published guidance accepts mailto, while recommending the RFC 8058 POST method.
- Separate lists: If subscribers can opt out of different lists, check that each message identifies its list and that one-click removes the recipient only from that list. Google recommends a List-ID header or a unique From address for each subscription list.
This distinction matters when auditing a company with newsletters, product notifications, and receipts. Test each subscribed stream against the applicable rule, and keep essential account mail out of a marketing suppression flow.
How to check it in Gmail
In Gmail, open the delivered email, choose the message menu, then choose Show original. Search the original source for List-Unsubscribe and List-Unsubscribe-Post. Read any indented continuation lines with the header above them. The send details box can show mailed-by, signed-by, and sometimes unsubscribe, but the original source shows the delivered headers.
Gmail message menu showing where to open the original message source.
Use a message that matches real production mail. Avoid a forwarded copy because forwarding can alter headers or break authentication. Send the original message from the same platform, domain, subdomain, template, and audience type used for real subscribed traffic.
|
|
|
|---|---|---|
Raw header | Direct proof of presence | High |
Post header | One-click declared | Medium |
DKIM h= coverage | Headers signed when that signature passes | High |
Gmail control | Mailbox UI clue | Medium |
No control | Not decisive | Low |
Fast interpretation of common Gmail signals.
If both headers are present in the original source and Gmail still does not show a visible unsubscribe control, move on to the endpoint and authentication checks. There is more detail on that display behavior in the related note on Gmail display behavior.
Run a live email test
Send a real email to a test address and inspect the received message. A static screenshot from your email platform is insufficient because some systems add unsubscribe headers only at final send time, for certain list types, or after a recipient is linked to a subscription record.
Email tester
Send a real email to this address. Suped shows a results button when the test is ready.
?/43tests passed
A live test catches a wrong template path, missing merge data, a header added to newsletters but not automations, or a sandbox sender that differs from the production domain. It tests what recipients receive.
Email tester sample report showing total score, email preview, issue summary, and per-section results
Suped's email tester places the unsubscribe header check beside authentication results. Suped's DMARC monitoring connects those results to domains and sending sources used by the company. A separate POST test still verifies unsubscribe processing.
What to inspect in the header
When reviewing the source, check the header syntax, unsubscribe method, endpoint behavior, and authentication. A header can be present but nonfunctional, so go past a simple text search.
Header check
- Name: The field name is List-Unsubscribe.
- URL: The HTTPS option points to a working unsubscribe endpoint.
- Mailto: A mailto option can accompany the URL, but it does not replace Google one-click POST.
- Format: Each URL or mailto value sits inside angle brackets.
One-click check
- Post line: The message includes List-Unsubscribe-Post.
- Value: Its value is List-Unsubscribe=One-Click.
- POST: The HTTPS endpoint accepts POST without extra user action or authentication.
- Scope: The request removes the recipient from the list connected to that message.
Endpoint safety matters. A crawler or security gateway can fetch links in a message. A plain GET request must not unsubscribe the recipient. RFC 8058 uses a POST signal, so basic GET requests should be harmless.
One-click POST testhttp
POST /o/abc HTTP/1.1 Host: u.example.com Content-Type: application/x-www-form-urlencoded List-Unsubscribe=One-Click
For an operational test, send that body to the HTTPS URL without cookies or HTTP authorization, confirm a successful 2xx response without a redirect, then verify the correct subscription record becomes unsubscribed. Check that active send queues suppress the recipient within the required processing window. A successful HTTP response alone does not prove suppression.
Risky pattern to avoidtext
List-Unsubscribe: <https://u.example.com/unsub?id=abc> Avoid unsubscribing the recipient on a plain GET request.
The URL must identify the recipient and list without extra POST fields. Use a per-recipient, hard-to-guess token in the URL and verify it on the server. A URL shared across the whole list can affect the wrong record or fail after a superficial test passes.
Verify DKIM covers both unsubscribe headers
Finding both unsubscribe fields and seeing dkim=pass are separate checks. RFC 8058 requires at least one valid DKIM signature to cover both List-Unsubscribe and List-Unsubscribe-Post. In the raw message, find a passing DKIM-Signature, then inspect its h= tag for both field names.
DKIM header coverage exampletext
DKIM-Signature: v=1; a=rsa-sha256; d=example.com; s=selector1; h=from:to:subject:date:list-unsubscribe:list-unsubscribe-post; bh=...; b=...
Header names are case-insensitive, so lowercase names in the h= list are valid. If the message has several DKIM signatures, at least one passing signature needs to include both fields. A passing SPF result or a separate DKIM signature that omits them does not satisfy this RFC 8058 check.
Check after final delivery
Inspect the delivered message, not a draft MIME file. A sending platform or relay can add, remove, or rewrite unsubscribe fields after an earlier DKIM signature was created, leaving the fields outside the valid signature's coverage.
Why authentication still matters
List-Unsubscribe does not replace email authentication. Gmail and Yahoo bulk sender requirements include authenticated mail, low complaint rates, and an easy unsubscribe path. For DMARC to pass, either SPF or DKIM must pass with a domain aligned to the visible From domain. A passing result for an unrelated domain is insufficient.
Verification confidence
Use these bands to decide when a List-Unsubscribe check is complete.
UI clue only
Low
A control appears in the mailbox interface.
Raw header found
Medium
The original source contains the List-Unsubscribe header.
One-click confirmed
High
The message has signed headers and the POST endpoint updates the right list.
Auth also passes
Best
The delivered message meets SPF, DKIM, and DMARC requirements for its sending route.
A domain-level view helps when several systems send mail. Suped's domain health checker checks DMARC, SPF, and DKIM records, while its DMARC platform monitors actual sending sources over time. This helps teams spot changes across marketing, billing, support, and product subdomains.
Where Suped fits
Use Suped's email tester to inspect a delivered sample, then its DMARC monitoring to identify sending sources and authentication changes. Test the one-click endpoint directly because DMARC reports do not verify unsubscribe processing.
Common failure patterns
Most failures are mismatches between the message path tested and the path subscribers receive. A newsletter has the header, but an automation does not. A staging sender has the header, but production strips it. A one-click line exists, but the endpoint returns a login page.
- Template split: Only some campaign types include the header, so test each major subscribed send path.
- Forwarded test: The tester checks a forwarded copy and sees altered headers.
- Unsigned fields: DKIM passes, but the valid signature's h= tag omits one or both unsubscribe headers.
- Bad endpoint: The POST URL requires a login, confirmation, preference choice, or captcha.
- Redirect: The POST endpoint returns a redirect instead of processing the request directly.
- GET unsubscribe: A link scanner can unsubscribe users because GET triggers the action.
- Body link missing: The headers work, but the message lacks a visible unsubscribe link.
- Delayed suppression: The endpoint records the request, but another send queue keeps mailing the recipient.
- Wrong scope: The action removes a user from unrelated lists instead of the list associated with the message.
For one-click behavior, test the actual POST path. A browser click on the visible footer link usually tests a preference center. Both can coexist, but they are different checks. The companion page on one-click testing covers that workflow.
A practical verification workflow
Use this workflow when a team needs a clear answer for marketing, engineering, or compliance. It keeps the test close to the live subscriber experience and avoids conclusions based only on a mailbox control.
- Send real mail: Use the same domain, template, list, and sending route as production.
- Open original: In Gmail, use Show original and search for both unsubscribe headers.
- Confirm syntax: Check the HTTPS URL, optional mailto value, and exact one-click POST header.
- Check DKIM coverage: Confirm one passing signature lists both unsubscribe headers in its h= tag.
- Test endpoint: Send the one-click POST without credentials or cookies and verify the right list changes.
- Check the body link: Confirm the message has a visible unsubscribe link that works.
- Check auth: Confirm SPF and DKIM setup and that DMARC passes through an aligned authenticated domain.
- Retest paths: Repeat for newsletters, lifecycle emails, subscription-based campaigns, and reactivation sends.
Flowchart for verifying List-Unsubscribe headers and one-click behavior.
Once the workflow passes, record a sample original header, the valid DKIM signature, the endpoint response, and the tested send path. That gives the team a reference if a future template, sender setting, DNS change, or sending domain change breaks the behavior. Suped's MSP and multi-tenant dashboard can help keep domain checks organized across clients or business units.
Views from the trenches
Best practices
Check the raw original source before trusting any mailbox unsubscribe UI signal.
Test the exact campaign path recipients receive, not a forwarded or staged copy.
Confirm the POST endpoint works without login, captcha, or extra preference steps.
Common pitfalls
A visible Gmail button gets treated as proof when it is only a partial interface signal.
Teams confirm List-Unsubscribe but forget the matching List-Unsubscribe-Post header.
Forwarded test emails alter headers and create false confidence or false alarms.
Expert tips
Save a known-good original header sample for each sender and major template path.
Keep GET requests harmless so security scanners cannot unsubscribe real users by mistake.
Review authentication at the same time because mailbox display checks rely on sender trust.
Expert from Email Geeks says the raw original source is the reliable place to confirm List-Unsubscribe and List-Unsubscribe-Post.
2024-01-10 - Email Geeks
Marketer from Email Geeks says a missing Gmail unsubscribe link should not trigger panic because the header can still be present.
2024-01-10 - Email Geeks
What to do next
To verify that your company's emails have List-Unsubscribe headers correctly configured, inspect the raw original message. The minimum proof is a valid List-Unsubscribe header. For RFC 8058 one-click unsubscribe, the message also needs an HTTPS URL and List-Unsubscribe-Post with List-Unsubscribe=One-Click, and one valid DKIM signature must cover both fields.
Test the HTTPS POST, confirm the correct subscription changes without extra user action, and check the visible body link. Then verify authentication on the same delivered message. Suped's product can keep message tests beside DMARC monitoring for the domains and sending sources in scope, while endpoint and suppression checks remain part of campaign QA.
