If bulk email compliance work is already underway, one-click unsubscribe is usually where teams discover that a footer link is not the same thing as a provider-recognized unsubscribe flow.
That distinction matters now.
Google's Email sender guidelines require bulk senders to support one-click unsubscribe for marketing and subscribed messages, and to include a clearly visible unsubscribe link in the message body. Google's sender FAQ also makes the practical part explicit: a mailto link or a normal body link does not satisfy Gmail's one-click requirement by itself.
Yahoo's Sender Requirements & Recommendations point in the same direction for bulk senders: easy unsubscribe, a visible body link, and honoring requests within 2 days. Yahoo says the RFC 8058 POST method is highly recommended.
So the safest implementation for mail that needs to work well at both Gmail and Yahoo is:
If the broader provider checklist is still being cleaned up, Gmail, Yahoo, and Microsoft email sender requirements is the bigger picture. This post stays focused on the unsubscribe part.
There are two related standards here:
List-Unsubscribe headerList-Unsubscribe-Post: List-Unsubscribe=One-Click so mailbox providers can tell the HTTPS URL is meant for a direct unsubscribe POSTThat second header is the important bit.
Without it, many senders fall back to a landing page or a confirmation click, because receivers and security tools may prefetch links. RFC 8058 exists specifically to avoid accidental unsubscribes caused by automated URL fetching while still allowing mailbox providers to offer a real unsubscribe action inside the mail client.
For Gmail, one-click unsubscribe is required for marketing and promotional mail from bulk senders. Transactional mail such as password resets, receipts, and reservation confirmations is not the target of this requirement, as Google's sender FAQ explains.
That means the first operational step is not "add these headers to everything".
It is:
If a stream mixes marketing and transactional content in the same messages, fix that first. Those mixed streams are where unsubscribe behavior and spam complaints get messy very quickly.
The minimal RFC 8058 pattern looks like this:
List-Unsubscribe: <https://example.com/unsubscribe/9f2c4a8e>, <mailto:unsubscribe@example.com?subject=unsubscribe>
List-Unsubscribe-Post: List-Unsubscribe=One-ClickThree details matter here:
List-Unsubscribe header must include one HTTPS URL for the one-click flow.mailto: entry can still be present as an additional option, but for Gmail it does not replace the HTTPS one-click path.List-Unsubscribe-Post header value must be exactly List-Unsubscribe=One-Click.That exact value is not decorative. RFC 8058 defines it as the signal that tells the receiver it can perform an HTTPS POST for a direct unsubscribe.
This is where many otherwise-correct implementations quietly miss the point.
The one-click URL should identify the recipient and list well enough that the unsubscribe can complete immediately. RFC 8058 recommends using an opaque or hard-to-forge identifier in the URL rather than trusting a plain email address alone.
The endpoint should behave like this:
POSTList-Unsubscribe=One-Click in the request bodyWhat it should not do:
RFC 8058 is explicit about several of those behaviors. The POST should stand on its own, and the unsubscribe target should already carry the information needed to process the request.
Keep the preference center if it is useful. Just do not make the RFC 8058 endpoint depend on that page. The body link can go to preferences. The one-click header target should directly process the unsubscribe.
This is the most common misunderstanding.
Teams often say, "There is already an unsubscribe link in the footer, so this is handled." For Gmail compliance, that is incomplete.
Google's sender FAQ says:
In other words:
For Gmail bulk senders, both matter.
Yahoo's guidance also expects a clearly visible body unsubscribe link, so this is not an either-or design. The operationally correct answer is header-based one-click plus a visible body link.
This part is easy to miss and important enough to check explicitly.
RFC 8058 requires a valid DKIM signature that covers at least these two headers:
List-UnsubscribeList-Unsubscribe-PostThat means the h= list in the DKIM-Signature header needs to include them.
Example pattern:
DKIM-Signature: v=1; a=rsa-sha256; d=example.com; s=mailer1;
h=from:to:subject:date:message-id:list-unsubscribe:list-unsubscribe-post;
bh=...; b=...If those headers are present in the message but not covered by DKIM, receivers have less reason to trust them, and the one-click flow may not be treated as eligible.
If DKIM handling still needs cleanup, DKIM selectors and key rotation playbook and DKIM key length and algorithms are the adjacent topics worth checking.
The cleanest rollout usually looks like this:
Put promotional and subscribed traffic on the code path where the headers will be added.
Use a token or opaque identifier that maps to:
Avoid plain links that only expose email=user@example.com with no protection.
Add both headers before signing.
Make sure the signing step happens after the unsubscribe headers are in place, and make sure both headers are included in the signed header list.
That body link can go to a preference page if wanted. Just do not confuse that page with the one-click endpoint.
Google recommends fulfilling unsubscribe requests within 48 hours in its sender FAQ. Yahoo says requests should be processed within 2 days in its sender requirements.
Operationally, faster is better. Slow unsubscribe handling turns a normal opt-out into a spam complaint.
Testing should cover both message construction and endpoint behavior.
In Gmail, open the message and use Show original.
Verify that:
List-Unsubscribe is presentList-Unsubscribe-Post: List-Unsubscribe=One-Click is presentWhere possible, confirm the delivered message source still contains the headers exactly as expected. This catches cases where an ESP added the headers in one path but not another.
The RFC 8058 POST is simple enough to test without guessing:
curl -i -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
--data "List-Unsubscribe=One-Click" \
"https://example.com/unsubscribe/9f2c4a8e"The test should confirm that the recipient is actually removed from the intended list and that no login, redirect chain, or confirmation page is required for success.
Even if Gmail is the immediate driver, Yahoo is part of the same compliance reality now. Send a live message through the same campaign path and confirm the headers survive the real outbound flow.
These are the ones that show up most often in production:
Many stacks have multiple mail paths: campaign mail, lifecycle mail, legacy mailers, ESP-specific adapters. One path gets the headers right; another silently does not.
That is a normal body-link design, but it is not RFC 8058 one-click behavior.
This is especially common when a downstream provider injects headers after the original signing step.
mailto: is present, but no HTTPS one-click endpoint existsThat may be acceptable for older list behavior, but it does not meet Gmail's one-click requirement.
If suppression runs in a delayed batch, users keep receiving mail after opting out. That is exactly when spam complaints rise.
Do not do that. Google requires a clearly visible body unsubscribe link for relevant bulk mail, and Yahoo expects the same general user experience.
For Gmail and Yahoo, a footer unsubscribe link by itself is no longer the full answer for bulk promotional mail.
The practical standard now is:
List-Unsubscribe with an HTTPS unsubscribe URLList-Unsubscribe-Post: List-Unsubscribe=One-ClickThat is the version that matches RFC 8058, matches what Gmail actually expects, and lines up well with Yahoo's current sender guidance.