One-Click List-Unsubscribe (RFC 8058)

Implement RFC 8058 one-click list unsubscribe headers with HTTP POST endpoints, mailto fallbacks, DKIM signature protection, and zero login barriers.

What it is

RFC 8058 defines a standardized, automated mechanism allowing email clients (Gmail, Apple Mail, Yahoo Mail, Outlook) to render a native “Unsubscribe” button at the top of the reading pane, enabling recipients to opt out of promotional streams with a single click.

The mechanism pairs two complementary headers:

List-Unsubscribe (RFC 2369): Declares one or more URIs (an HTTPS endpoint and an optional mailto: fallback).
List-Unsubscribe-Post (RFC 8058): Declares the exact POST body required for the automated one-click transaction (List-Unsubscribe=One-Click).

List-Unsubscribe: <https://example.com/api/unsubscribe/v1?token=f81d4fae7dec>, <mailto:[email protected]?subject=unsub_f81d4fae7dec>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

When a user clicks the native “Unsubscribe” banner, the mailbox provider executes an HTTP POST request to the provided HTTPS URI with a payload of List-Unsubscribe=One-Click.

Why it matters

Mandatory Compliance for Bulk Senders: Google and Yahoo strictly mandate RFC 8058 one-click unsubscribe support for all senders dispatching 5,000+ messages per day. Non-compliant senders face aggressive throttling and delivery rejection.
Dramatically Reduces Spam Complaints: Frustrated users who cannot quickly find an unsubscribe link will click “Report Spam”. Providing an instantaneous, native unsubscribe button at the top of the client converts potential spam complaints into benign list removals.
Anti-Scraping & Pre-fetch Safety: Automated email security gateways (proofpoint, mimecast, corporate firewalls) routinely pre-fetch and click all GET links inside incoming emails. By requiring an HTTP POST transaction for actual unsubscription, RFC 8058 ensures that automated scanners do not inadvertently unsubscribe users.

How to implement

1. Emit both RFC 8058 headers on all commercial and marketing mail: Include both the HTTPS URL and the mailto: fallback in List-Unsubscribe:

List-Unsubscribe: <https://mail.example.com/unsub/token-992384>, <mailto:[email protected]>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

2. Cryptographically sign both headers with DKIM: RFC 8058 §4 strictly requires that both List-Unsubscribe and List-Unsubscribe-Post MUST be included in the DKIM h= header signing list:

DKIM-Signature: v=1; a=rsa-sha256; d=example.com; s=202608;
 h=from:to:subject:date:list-unsubscribe:list-unsubscribe-post:...;

If these headers are not covered by a passing, aligned DKIM signature, mailbox providers will ignore the one-click headers and disable the native UI button.

3. Implement the HTTP POST Endpoint Handler: The HTTPS endpoint must process the unsubscription without presenting a login prompt, CAPTCHA, or confirmation landing page:

// Example Express / Node.js handler
app.post("/unsub/:token", async (req, res) => {
  const { token } = req.params;
  const isOneClick = req.body["List-Unsubscribe"] === "One-Click";

  // 1. Validate cryptographic token
  const subscriber = await db.verifyUnsubscribeToken(token);
  if (!subscriber) return res.status(404).send("Invalid Token");

  // 2. Suppress subscriber from marketing list
  await db.suppressSubscriber(subscriber.email, "ONE_CLICK_UNSUB");

  // 3. Return 200 OK
  return res.status(200).send("Unsubscribed successfully.");
});

4. Honor Unsubscribe Requests within 48 Hours: Google and industry standards require unsubscribe requests to be processed and effective across all active campaigns within 48 hours (and immediately for direct API hooks).

Common mistakes

Returning a 302 Redirect to a Login Page: Requiring the user to log in or enter an email address to complete unsubscription violates RFC 8058 and causes mailbox providers to permanently disable the one-click banner.
Handling Only HTTP GET: When a user clicks “Unsubscribe” in Gmail, Gmail sends an HTTP POST. If your server only handles GET requests, the unsubscribe operation fails.
Unsubscribing from Transactional Emails: Never attach List-Unsubscribe headers to mandatory transactional notifications (password resets, invoice receipts, security alerts).
Omitting mailto: Fallback: Some desktop clients (such as older Outlook versions) only support mailto: unsubscriptions. Always provide both HTTPS and mailto:.

Verification

1. Simulate RFC 8058 POST request with curl:

curl -X POST https://mail.example.com/unsub/token-992384 \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "List-Unsubscribe=One-Click" -i
# Verify: HTTP/1.1 200 OK returned immediately

2. Verify DKIM header inclusion in test message:

grep -i "h=" raw_email.eml | grep -i "list-unsubscribe"