A List-Unsubscribe header gives a mailbox provider a machine-readable way to unsubscribe a recipient. For one-click, you need two headers, a DKIM signature that covers both, and an endpoint that accepts an unauthenticated POST. Google requires it for bulk senders over 5,000 messages per day. Microsoft’s guidance is less specific, but it still expects a working unsubscribe path.
What the List-Unsubscribe header does
The List-Unsubscribe header is defined in RFC 2369. It tells the mailbox provider where to send an unsubscribe request. The header can contain a mailto unsubscribe URI and an HTTPS unsubscribe URL. The provider chooses which path to use.
This is a header, not the visible unsubscribe link in the message body. You still need a visible link that a person can click. The header is what lets Gmail, Apple Mail, Yahoo Mail, and other clients show their own unsubscribe control.
Without one-click, the provider may send an email or open a page. With one-click, the provider can complete the request in the background.
The two headers: List-Unsubscribe and List-Unsubscribe-Post
One-click needs both headers. The first gives the unsubscribe path; the second signals that the HTTPS path supports a one-click POST.
“text List-Unsubscribe: <mailto:unsubscribe@example.com>, <https://example.com/unsubscribe?u=abc> List-Unsubscribe-Post: List-Unsubscribe=One-Click “
The List-Unsubscribe=One-Click value is the signal defined by RFC 8058. The HTTPS URI must identify the recipient and the list. There are no extra POST arguments, so the identifier has to be inside the URL. The mailto option can remain as an alternative, but one-click requires the HTTPS unsubscribe URL.
RFC 8058: what one-click actually requires
RFC 8058 is specific, and most broken implementations miss one of these conditions:
- One List-Unsubscribe header with one HTTPS URI. It may also contain a mailto URI.
- One List-Unsubscribe-Post header with the value
List-Unsubscribe=One-Click. - A valid DKIM signature that covers both headers. The DKIM
h= tagmust includeList-UnsubscribeandList-Unsubscribe-Post. If the signature does not cover them, the receiver should not offer one-click. - A POST request with no cookies, no HTTP authorization, and no other context information.
- No HTTPS redirect after the POST. Redirected POSTs are unreliable and can turn into GETs.
- A URI that identifies the recipient and the list, with an opaque or hard-to-forge component.
- A server that handles the POST and completes the unsubscribe without a login or confirmation page.
The DKIM condition is the one to check first. Many senders publish both headers and still fail one-click because their sending platform does not include the headers in the DKIM signature. If you use an ESP, ask whether it signs both headers. If it does not, move the unsubscribe flow to a platform that does, or sign the message yourself.
Google and Microsoft: what each provider expects
Google is explicit for bulk senders. Microsoft’s high-volume guidance is more general, and its authentication requirements are separate.
| Provider | One-click | Visible link | Timing | Notes |
|---|---|---|---|---|
| Required for bulk senders over 5,000 messages per day | Required | Process within 48 hours | Both headers required | |
| Microsoft 365 and Outlook | Functional unsubscribe expected; RFC 8058 is not spelled out in the high-volume guidance | Visible and functional link | Check current Microsoft guidance | Separate SPF, DKIM, and DMARC requirements |
Google says marketing messages and subscribed messages must support one-click unsubscribe and include a clearly visible unsubscribe link in the body. The one-click rule applies to senders over 5,000 messages per day to Gmail personal accounts, but the visible link is good practice at any volume.
Microsoft’s high-volume guidance asks for functional unsubscribe links and list hygiene. It does not use the same RFC 8058 wording as Google, so do not assume that meeting one provider automatically meets the other. Publishing both headers is still the safest path.
Implementation: headers, DKIM coverage, and the unsubscribe endpoint
A working one-click flow has six parts:
1. Build an HTTPS unsubscribe URL with an opaque identifier for the recipient and the list. Do not rely on a plain email address in the query string. 2. Add the List-Unsubscribe header with the HTTPS unsubscribe URL, and optionally a mailto unsubscribe URI. 3. Add the List-Unsubscribe-Post header with List-Unsubscribe=One-Click. 4. Make sure DKIM covers both headers. Check the h= tag in the signature, not just the header presence. 5. Accept a POST at the unsubscribe URL with no cookies or authorization. Return a successful response, do not redirect, and make the operation idempotent. 6. Add a visible unsubscribe link in the body, honor the request within 48 hours, and suppress the recipient across every sending system.
If the endpoint requires a login, shows a confirmation page, or redirects to a marketing page, one-click will fail even if both headers are present.
Common failure modes
| Symptom | Likely cause | Fix |
|---|---|---|
| Gmail shows no one-click option | One header is missing | Add both List-Unsubscribe and List-Unsubscribe-Post |
| Headers exist but one-click fails | DKIM h= tag does not cover both headers | Include both headers in the DKIM signature |
| Click opens a page or login | GET-only endpoint, redirect, or authentication required | Accept POST, remove redirects, remove auth |
| Only mailto works | No HTTPS unsubscribe URL | Add an HTTPS URI to List-Unsubscribe |
| Unsubscribe is not honored | Request is logged but not suppressed everywhere | Process within 48 hours and sync the suppression list |
| Works in one client, not another | Provider support or format differences | Test Gmail, Apple Mail, Yahoo Mail, and Outlook separately |
| No visible unsubscribe link | Header exists, body link missing | Add a clearly visible link in the message body |
Reverse DNS and tracking domains
One-click is only one part of the infrastructure. Two other gaps show up in B2B outbound.
Reverse DNS. A reverse DNS lookup maps an IP address to a hostname through a PTR record. Microsoft says it may not accept mail from senders that fail a reverse-DNS lookup. The PTR record should match the hostname your server uses in HELO or EHLO. This matters most for dedicated or static IPs; a shared ESP normally manages it for you. Check it with dig -x and confirm that the result matches the sending host.
Tracking domains. A branded tracking domain uses a CNAME such as track.example.com and serves links over HTTPS with a valid certificate. Avoid a shared tracking domain with a poor reputation. The body link domain does not change SPF or DKIM alignment, but a mismatched or shared tracking domain can hurt sender reputation, inbox placement, and click measurement. Keep redirects working and test every link after a domain change.
Neither item replaces authentication. For the full sequence, use our cold email deliverability checklist. If you are also evaluating BIMI, the BIMI record requirements guide covers the separate DMARC and certificate path.
How to verify one-click unsubscribe
Verification is more than checking that the headers exist.
1. Send a test to a Gmail mailbox and open the original message. Confirm that both headers are present. 2. Check the DKIM signature and confirm that the h= tag includes both headers. 3. Use the Gmail unsubscribe control. Confirm that the POST reaches your endpoint and the recipient is suppressed. 4. Repeat the test in Apple Mail and Yahoo Mail. Check Outlook separately, because its behavior and support differ. 5. Click the visible unsubscribe link in the body. Confirm that it works without a login. 6. Check your logs and CRM. A successful HTTP response is not enough; the recipient must be suppressed everywhere.
FAQ
What is a List-Unsubscribe header?
A List-Unsubscribe header tells a mailbox provider where to send an unsubscribe request. It can contain a mailto URI and an HTTPS unsubscribe URL. It is separate from the visible unsubscribe link in the message body.
What is the difference between List-Unsubscribe and List-Unsubscribe-Post?
List-Unsubscribe gives the unsubscribe path. List-Unsubscribe-Post with List-Unsubscribe=One-Click tells the provider that the HTTPS path supports a one-click POST. Both are required for RFC 8058 one-click.
Do I need one-click unsubscribe for cold email?
Google requires one-click for bulk senders over 5,000 messages per day. At lower volume, a visible unsubscribe link is still expected. Publishing both headers is the safest setup for any commercial or subscribed message.
Why is Gmail not showing the one-click button?
The most common causes are a missing List-Unsubscribe-Post header, a DKIM signature that does not cover both headers, a GET-only endpoint, or a redirect after the POST. Check the headers and the h= tag first.
Does reverse DNS affect deliverability?
It can. Microsoft says it may not accept mail from senders that fail a reverse-DNS lookup. The PTR record should match the sending host. Reverse DNS is not a substitute for SPF, DKIM, or DMARC.
When to get help
If you want a second pair of eyes on your headers, DKIM coverage, or unsubscribe endpoint, book a free deliverability audit and we will test the full path before you send another campaign. If you need the full outbound service, start with our cold email outreach service page.