List-Unsubscribe validator: RFC 8058 and Gmail/Yahoo bulk-sender headers

RFC 8058 defines the one-click unsubscribe: a List-Unsubscribe: header carrying an https URL, plus a List-Unsubscribe-Post: List-Unsubscribe=One-Click header telling the mailbox provider it may POST to that URL without asking the reader to confirm. Gmail and Yahoo made one-click a requirement for bulk senders in February 2024 — any sender pushing more than 5,000 messages a day to Gmail or Yahoo addresses needs the headers on every message, alongside authenticated mail (SPF pass, DKIM pass aligned with the From: domain, DMARC pass). Miss any of the four and the receiver either buckets the message into spam or, past a threshold, rejects it at the edge.

The compliance signal is header-shaped, so it can be checked statically from a copy of the raw source of a sent message. This validator grades the seven signals in one pass: the four RFC 8058 header-level checks and the three Authentication-Results verdicts Gmail and Yahoo pin the bulk-sender floor to. It runs entirely in your browser; the pasted headers are never uploaded.

Paste raw email headers

<button type="button" class="nanopost-tool__submit" data-luv-parse>Validate</button>
    <button type="button" class="nanopost-luv__clear" data-luv-clear>Clear</button>
    <button type="button" class="nanopost-luv__sample" data-luv-sample>Load sample</button>
    <noscript>
      <p class="nanopost-tool__notice nanopost-tool__notice--info">
        Parsing runs in your browser, so JavaScript needs to be on. With JS off,
        look for a <code>List-Unsubscribe:</code> header, a
        <code>List-Unsubscribe-Post: List-Unsubscribe=One-Click</code> header,
        and an <code>Authentication-Results:</code> line showing
        <code>spf=pass dkim=pass dmarc=pass</code> to satisfy the Gmail/Yahoo
        bulk-sender rules.
      </p>
    </noscript>
  </div>

<p class="nanopost-tool__foot">
    <strong>This is a static check.</strong> It confirms the compliance headers
    are present and well-formed, and that the SPF/DKIM/DMARC verdicts the
    receiver stamped satisfy the bulk-sender rules. It does not fire the
    one-click POST against your unsubscribe endpoint — a header can be present
    and the endpoint still return 500 to the mailbox provider’s probe. A live
    tester ships separately. Parsing runs entirely in your browser; no upload
    endpoint.
  </p>
</div>
</p>

<h2 class="wp-block-heading">What the tool checks</h2>

<p class="wp-block-paragraph"><strong>RFC 8058 (four checks):</strong></p>

<li><code>List-Unsubscribe:</code> header is present.</li>

<li>Its value contains at least one <code><https://…></code> URL. A bare <code><mailto:…></code> isn’t RFC 8058 compliant on its own — the one-click POST is HTTP-only.</li>

<li><code>List-Unsubscribe-Post:</code> header is present with the exact value <code>List-Unsubscribe=One-Click</code>.</li>

<li>The https URL parses cleanly — has a scheme, has a hostname, isn’t a bare IP literal.</li>

</ul>

<p class="wp-block-paragraph"><strong>Gmail / Yahoo bulk-sender floor (three additional checks):</strong></p>

<li>The receiver’s <code>Authentication-Results:</code> line records <code>spf=pass</code> on the Return-Path domain.</li>

<li>Records <code>dkim=pass</code> on a signature whose <code>header.d</code> aligns with the From: domain (relaxed alignment on the eTLD+1).</li>

<li>Records <code>dmarc=pass</code>.</li>

</ul>

<p class="wp-block-paragraph">All seven pass and you have both verdicts — the compliance floor at the receiver is met.</p>

<h2 class="wp-block-heading">Static check versus live one-click test</h2>

<p class="wp-block-paragraph">The header can be present, well-formed, and still not work. The RFC 8058 spec requires the endpoint to accept an HTTP POST with an empty body and return a 2xx response — Gmail and Yahoo periodically probe the endpoint from their side, and if it 5xx’s, times out, or requires cookies, they treat the sender as if the header weren’t there. A static header check is a necessary-not-sufficient signal: it catches the common failure mode (header missing, wrong value, mailto-only), but it can’t catch a broken endpoint.</p>

<p class="wp-block-paragraph">The <a href="/tools/list-unsub-live-tester/">live list-unsubscribe tester</a> fires an actual POST against the endpoint and reads the response code, headers, and timing. Static check first, live POST second.</p>

<h2 class="wp-block-heading">How to get raw headers</h2>

<li><strong>Gmail / Google Workspace.</strong> Open the message. Three-dot menu → <em>Show original</em>. Copy from the top of the raw source down through the blank line that ends the header block.</li>

<li><strong>Outlook (web) / Microsoft 365.</strong> Three-dot menu → <em>View → View message source</em>. Copy the header block.</li>

<li><strong>Apple Mail (macOS).</strong> <em>View → Message → Raw Source</em>.</li>

<li><strong>Thunderbird.</strong> <em>View → Message Source</em> (<code>Ctrl+U</code>).</li>

</ul>

<p class="wp-block-paragraph">Paste into the textarea above. The tool parses in your browser — nothing crosses the network.</p>

<h2 class="wp-block-heading">Why the four RFC 8058 checks read the way they do</h2>

<p class="wp-block-paragraph">The <code>List-Unsubscribe:</code> header predates one-click by more than a decade — RFC 2369 (1998) defined it as a comma-separated list of <code><URI></code> entries so mail clients could offer an “unsubscribe” button on newsletters. That original spec allowed <code>mailto:</code> URIs and expected a reader interaction, so a lot of legacy campaign infrastructure emits <code>List-Unsubscribe: <mailto:…></code> and stops there. It’s compliant with RFC 2369; it’s not compliant with RFC 8058.</p>

<p class="wp-block-paragraph">RFC 8058 tightens the header in two ways. First, at least one URI must be an https URL — mailbox providers need a target they can POST to, and the empty-body POST semantics only make sense over HTTP. Second, the <code>List-Unsubscribe-Post:</code> header (also introduced by 8058) has to be present and has to carry exactly the value <code>List-Unsubscribe=One-Click</code>, which is the sender’s affirmation that “yes, POSTing to the URL above is an unsubscribe — no confirmation page, no CAPTCHA.”</p>

<p class="wp-block-paragraph">The URL-sanity check catches the mistakes that make an endpoint impossible to POST to before you deploy: a <code>List-Unsubscribe: <https:></code> with no host, a hostname that’s a bare IP (mailbox providers won’t POST to those), or a scheme mismatch. It’s cheap and it saves you a live-tester round trip.</p>

<h2 class="wp-block-heading">Why the Gmail/Yahoo floor is stricter than one-click alone</h2>

<p class="wp-block-paragraph">One-click on its own doesn’t reach the bulk-sender floor. Both providers require the sending domain to be authenticated end-to-end — SPF pass on the envelope-from, an aligned DKIM signature, and a DMARC pass — so that the unsubscribe request Gmail or Yahoo eventually POSTs on the reader’s behalf is going to a domain the sender actually controls. Without alignment, a compromised or spoofed sender could ship the compliance headers and use the endpoint as a channel for something else entirely.</p>

<p class="wp-block-paragraph">That’s why the tool grades the seven signals as a set. A green RFC 8058 verdict with a red bulk-sender verdict tells you the headers are right but the auth story isn’t; a red RFC 8058 verdict is a message that will never satisfy the bulk-sender rules regardless of how the domain authenticates.</p>

<h2 class="wp-block-heading">When you’re ready to check further</h2>

<li>The <a href="/tools/header-auth-visualizer/">header auth visualizer</a> reads the same header block into a visual SPF / DKIM / DMARC / ARC chain — useful for tracing a <code>dmarc=fail</code> back to which mechanism didn’t align.</li>

<li>The <a href="/tools-dns-auth-checker/">DNS auth checker</a> reads the live SPF, DKIM, DMARC, MTA-STS, and TLS-RPT records for a domain over DNS-over-HTTPS and scores them against the same Gmail, Yahoo, and Microsoft 365 bulk-sender requirements. It’s the check to run before you flip a sending domain into production.</li>

</ul>
</div></div>

<footer class="site-footer wp-block-template-part">
<div class="wp-block-group alignfull has-main-color has-base-background-color has-text-color has-background has-link-color wp-elements-ae4aac6794c17dc14c0412bd32b9e242 has-global-padding is-layout-constrained wp-container-core-group-is-layout-63f1d60a wp-block-group-is-layout-constrained" style="border-top-color:var(--wp--preset--color--border-light);border-top-width:1px;margin-top:0px;padding-top:var(--wp--preset--spacing--xx-large);padding-right:var(--wp--preset--spacing--medium);padding-bottom:var(--wp--preset--spacing--xx-large);padding-left:var(--wp--preset--spacing--medium)">
<div class="wp-block-columns alignwide is-layout-flex wp-container-core-columns-is-layout-d064aeaa wp-block-columns-is-layout-flex">
<div class="wp-block-column is-layout-flow wp-block-column-is-layout-flow"><p class="has-link-color wp-elements-f89e54a87e09ad25ba6ef7404bf88732 wp-block-site-title has-text-color has-main-color">nanoPost</p>

<p class="has-small-font-size wp-block-paragraph">Independent reviews and how-tos for getting WordPress email out the door, into the inbox, and staying there.</p>

<div class="wp-block-group is-nowrap is-layout-flex wp-container-core-group-is-layout-fe6f0742 wp-block-group-is-layout-flex">
<div class="wp-block-group has-border-color has-main-border-color has-global-padding is-layout-constrained wp-container-core-group-is-layout-ca8d93cb wp-block-group-is-layout-constrained" style="border-width:1px;padding-top:3px;padding-right:3px;padding-bottom:3px;padding-left:3px">
<ul class="wp-block-social-links has-large-icon-size has-icon-color has-icon-background-color is-style-default is-content-justification-left is-layout-flex wp-container-core-social-links-is-layout-90a3c330 wp-block-social-links-is-layout-flex"><li style="color:#171A1F;background-color:#fff" class="wp-social-link wp-social-link-twitter has-main-color has-base-background-color wp-block-social-link"><a href="https://twitter.com/nanopo_st" class="wp-block-social-link-anchor"><svg width="24" height="24" viewBox="0 0 24 24" version="1.1" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false"><path d="M22.23,5.924c-0.736,0.326-1.527,0.547-2.357,0.646c0.847-0.508,1.498-1.312,1.804-2.27 c-0.793,0.47-1.671,0.812-2.606,0.996C18.324,4.498,17.257,4,16.077,4c-2.266,0-4.103,1.837-4.103,4.103 c0,0.322,0.036,0.635,0.106,0.935C8.67,8.867,5.647,7.234,3.623,4.751C3.27,5.357,3.067,6.062,3.067,6.814 c0,1.424,0.724,2.679,1.825,3.415c-0.673-0.021-1.305-0.206-1.859-0.513c0,0.017,0,0.034,0,0.052c0,1.988,1.414,3.647,3.292,4.023 c-0.344,0.094-0.707,0.144-1.081,0.144c-0.264,0-0.521-0.026-0.772-0.074c0.522,1.63,2.038,2.816,3.833,2.85 c-1.404,1.1-3.174,1.756-5.096,1.756c-0.331,0-0.658-0.019-0.979-0.057c1.816,1.164,3.973,1.843,6.29,1.843 c7.547,0,11.675-6.252,11.675-11.675c0-0.178-0.004-0.355-0.012-0.531C20.985,7.47,21.68,6.747,22.23,5.924z"></path></svg><span class="wp-block-social-link-label screen-reader-text">Twitter</span></a></li></ul>
</div>

<div class="wp-block-group has-border-color has-main-border-color has-global-padding is-layout-constrained wp-container-core-group-is-layout-ca8d93cb wp-block-group-is-layout-constrained" style="border-width:1px;padding-top:3px;padding-right:3px;padding-bottom:3px;padding-left:3px">
<ul class="wp-block-social-links has-large-icon-size has-icon-color has-icon-background-color is-style-default is-content-justification-left is-layout-flex wp-container-core-social-links-is-layout-90a3c330 wp-block-social-links-is-layout-flex"><li style="color:#171A1F;background-color:#fff" class="wp-social-link wp-social-link-github has-main-color has-base-background-color wp-block-social-link"><a href="https://github.com/nanoPost" class="wp-block-social-link-anchor"><svg width="24" height="24" viewBox="0 0 24 24" version="1.1" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false"><path d="M12,2C6.477,2,2,6.477,2,12c0,4.419,2.865,8.166,6.839,9.489c0.5,0.09,0.682-0.218,0.682-0.484 c0-0.236-0.009-0.866-0.014-1.699c-2.782,0.602-3.369-1.34-3.369-1.34c-0.455-1.157-1.11-1.465-1.11-1.465 c-0.909-0.62,0.069-0.608,0.069-0.608c1.004,0.071,1.532,1.03,1.532,1.03c0.891,1.529,2.341,1.089,2.91,0.833 c0.091-0.647,0.349-1.086,0.635-1.337c-2.22-0.251-4.555-1.111-4.555-4.943c0-1.091,0.39-1.984,1.03-2.682 C6.546,8.54,6.202,7.524,6.746,6.148c0,0,0.84-0.269,2.75,1.025C10.295,6.95,11.15,6.84,12,6.836 c0.85,0.004,1.705,0.114,2.504,0.336c1.909-1.294,2.748-1.025,2.748-1.025c0.546,1.376,0.202,2.394,0.1,2.646 c0.64,0.699,1.026,1.591,1.026,2.682c0,3.841-2.337,4.687-4.565,4.935c0.359,0.307,0.679,0.917,0.679,1.852 c0,1.335-0.012,2.415-0.012,2.741c0,0.269,0.18,0.579,0.688,0.481C19.138,20.161,22,16.416,22,12C22,6.477,17.523,2,12,2z"></path></svg><span class="wp-block-social-link-label screen-reader-text">GitHub</span></a></li></ul>
</div>
</div>
</div>

<div class="wp-block-column is-layout-flow wp-block-column-is-layout-flow">
<div class="wp-block-columns is-layout-flex wp-container-core-columns-is-layout-8d39b2df wp-block-columns-is-layout-flex">
<div class="wp-block-column is-layout-flow wp-block-column-is-layout-flow">
<p class="wp-block-paragraph" style="font-style:normal;font-weight:600;text-transform:uppercase">Top Links</p>

<div class="wp-block-group has-small-font-size has-global-padding is-layout-constrained wp-container-core-group-is-layout-b56e0895 wp-block-group-is-layout-constrained">
<p class="wp-block-paragraph"><a href="https://nanopo.st/best/">Best of nanoPost</a></p>

<p class="wp-block-paragraph"><a href="https://nanopo.st/how-to/wordpress-email-setup-ultimate-guide/">How to Set Up Email on WordPress</a></p>

<p class="wp-block-paragraph"><a href="https://nanopo.st/how-to/troubleshoot-wordpress-email/">Troubleshoot WordPress email</a></p>

<p class="wp-block-paragraph"><a href="https://nanopo.st/best/free-smtp-servers-for-wordpress/">Free SMTP Servers for WordPress</a></p>

<p class="wp-block-paragraph"><a href="https://nanopo.st/wordpress-without-the-plugin/">WordPress without the plugin</a></p>
</div>
</div>

<p class="wp-block-paragraph"><a href="https://nanopo.st/contact/">Contact us</a></p>

<p class="wp-block-paragraph"><a href="https://nanopo.st/privacy/">Privacy Policy</a></p>

<p class="wp-block-paragraph"><a href="https://nanopo.st/terms/">Terms of Use</a></p>

<p class="wp-block-paragraph"><a href="https://nanopo.st/terms/#affiliate-disclosure">Affiliate Disclosure</a></p>

<p class="wp-block-paragraph"><a href="https://nanopo.st/write-for-us/">Write for us</a></p>
</div>
</div>
</div>
</div>
</div>

<div class="wp-block-group alignwide has-secondary-color has-text-color has-link-color wp-elements-38d3570061051c2c072b4a4cf8b78c5c is-layout-flow wp-block-group-is-layout-flow" style="padding-top:40px">
<div class="wp-block-group is-content-justification-space-between is-layout-flex wp-container-core-group-is-layout-fb93ea7c wp-block-group-is-layout-flex">
<p class="has-small-font-size wp-block-paragraph">© 2026 <a href="https://nanopo.st/">nanoPost</a> | <a href="https://nanopo.st/">WordPress email problems solved</a></p>
</div>
</div>
</div>

</footer></div>
<script type="speculationrules">
{"prefetch":[{"source":"document","where":{"and":[{"href_matches":"/*"},{"not":{"href_matches":["/wp-*.php","/wp-admin/*","/wp-content/uploads/*","/wp-content/*","/wp-content/plugins/*","/wp-content/themes/ollie/*","/*\\?(.+)"]}},{"not":{"selector_matches":"a[rel~=\"nofollow\"]"}},{"not":{"selector_matches":".no-prefetch, .no-prefetch a"}}]},"eagerness":"conservative"}]}
</script>
<script data-wp-router-options="{"loadOnClientNavigation":true}" fetchpriority="low" id="@wordpress/block-library/navigation/view-js-module" src="https://nanopo.st/wp-includes/js/dist/script-modules/block-library/navigation/view.min.js?ver=96a846e1d7b789c39ab9" type="module"></script>
<script id="wp-hooks-js" src="https://nanopo.st/wp-includes/js/dist/hooks.min.js?ver=7496969728ca0f95732d"></script>
<script id="wp-i18n-js" src="https://nanopo.st/wp-includes/js/dist/i18n.min.js?ver=781d11515ad3d91786ec"></script>
<script id="wp-i18n-js-after">
wp.i18n.setLocaleData( { 'text direction\u0004ltr': [ 'ltr' ] } );
//# sourceURL=wp-i18n-js-after
</script>
<script id="swv-js" src="https://nanopo.st/wp-content/plugins/contact-form-7/includes/swv/js/index.js?ver=6.1.7"></script>
<script id="contact-form-7-js-before">
var wpcf7 = {
    "api": {
        "root": "https:\/\/nanopo.st\/wp-json\/",
        "namespace": "contact-form-7\/v1"
    }
};
//# sourceURL=contact-form-7-js-before
</script>
<script id="contact-form-7-js" src="https://nanopo.st/wp-content/plugins/contact-form-7/includes/js/index.js?ver=6.1.7"></script>
<script id="nanopost-list-unsub-validator-js" src="https://nanopo.st/wp-content/plugins/nanopost-list-unsub-validator/assets/validator.js?ver=0.1.1"></script>
<script id="nanopost-embeds-compare-js" src="https://nanopo.st/wp-content/plugins/nanopost-snippets/snippets/../js/embeds-compare.js?ver=1781507079"></script>
<script id="nanopost-np-term-js" src="https://nanopo.st/wp-content/plugins/nanopost-snippets/snippets/../js/np-term.js?ver=1781793474"></script>
<script id="ollie-extensions-animation-js" src="https://nanopo.st/wp-content/plugins/ollie-pro/inc/extensions/build/animation-frontend.js?ver=2.7.1"></script>
<script id="ollie-pro-scroll-resize-js" src="https://nanopo.st/wp-content/plugins/ollie-pro/inc/extensions/loader/scroll-resize/scroll-resize-frontend.js?ver=2.7.1"></script>
<script id="ollie-extensions-advanced-group-js" src="https://nanopo.st/wp-content/plugins/ollie-pro/inc/extensions/build/advanced-group-frontend.js?ver=2.7.1"></script>
</body>
</html>