← RFC Reference

RFC 8058: One-Click Unsubscribe for Email

Why This Exists

RFC 2369's List-Unsubscribe header had a fundamental problem: email clients could not safely act on the URL automatically. An HTTPS URL might lead to a page with a CAPTCHA, a login form, a confirmation step, or even a malicious site. Clients had to open a browser and let the user handle it — adding friction that discouraged use.

RFC 8058 solves this by introducing the List-Unsubscribe-Post header. When present alongside an HTTPS List-Unsubscribe URL, it signals that the email client can send an HTTP POST request directly to unsubscribe the user — no browser, no confirmation, one click.

Since February 2024, Gmail and Yahoo require RFC 8058 compliance for bulk senders (those sending more than 5,000 messages per day to their users). This is no longer optional for commercial email.

How It Works

The mechanism requires two headers working together:

Required Headers

List-Unsubscribe: <https://example.com/unsub?id=abc123>,
    <mailto:unsub-abc123@example.com>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

When the email client sees both headers:

1. It displays a prominent "Unsubscribe" button in the UI.
2. When the user clicks it, the client sends an HTTP POST to the HTTPS URL from List-Unsubscribe.
3. The POST body is exactly: List-Unsubscribe=One-Click
4. The sender's server processes the POST and unsubscribes the user.

The HTTP POST Request

POST /unsub?id=abc123 HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 26

List-Unsubscribe=One-Click

The Server Response

The server should return a 200 OK status to confirm the unsubscribe succeeded. Any 2xx response indicates success. The response body is not displayed to the user, so it can be empty or contain a simple confirmation.

Key Technical Details

Header Requirements

• The List-Unsubscribe-Post header value must be exactly List-Unsubscribe=One-Click — no variations.
• The List-Unsubscribe header must include at least one HTTPS URL (not HTTP). The mailto URI is optional but recommended as a fallback.
• Both headers must be present on the same message. List-Unsubscribe-Post without List-Unsubscribe is meaningless.

DKIM Requirement

The message must pass DKIM authentication, and the DKIM signature must cover both the List-Unsubscribe and List-Unsubscribe-Post headers. This prevents attackers from injecting or modifying unsubscribe URLs in transit. Gmail explicitly checks this.

Endpoint Implementation

; Minimal server-side handler (pseudocode)
function handleUnsubscribe(request):
    if request.method != "POST":
        return 405 Method Not Allowed

    if request.body != "List-Unsubscribe=One-Click":
        return 400 Bad Request

    subscriberId = request.queryParams["id"]
    suppressRecipient(subscriberId)
    return 200 OK

Complete Message Headers Example

From: newsletter@example.com
To: user@gmail.com
Subject: Your Weekly Update
MIME-Version: 1.0
DKIM-Signature: v=1; a=rsa-sha256; d=example.com; s=sel1;
    h=from:to:subject:list-unsubscribe:list-unsubscribe-post;
    b=...
List-Unsubscribe: <https://example.com/unsub?id=abc123>,
    <mailto:unsub-abc123@example.com>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
Content-Type: text/html; charset=utf-8

Common Mistakes

• Using HTTP instead of HTTPS. The URL in List-Unsubscribe must use HTTPS. Email clients will not send POST requests to plain HTTP endpoints.
• Requiring confirmation after the POST. The point of one-click is one click. The POST alone must complete the unsubscribe. Do not send a confirmation email asking the user to "click to confirm" — this defeats the purpose.
• Not covering headers in DKIM signature. If your DKIM signature does not include list-unsubscribe and list-unsubscribe-post in the h= tag, Gmail will not trust the headers and will not show the one-click button.
• Returning errors or redirects. The endpoint must return a 2xx status code. Returning 301/302 redirects, 403 Forbidden, or 500 errors will cause the unsubscribe to fail and may trigger the user to report spam instead.
• URL expiration. Some senders use signed URLs with short expiration times. If the URL expires before the user clicks "Unsubscribe" (which could be weeks after receiving the message), the unsubscribe fails. Use long-lived or non-expiring tokens.
• GET-based unsubscribe. The endpoint must handle POST, not GET. A GET-based unsubscribe URL can be triggered by email link scanners, preview bots, or security tools — unsubscribing users who never clicked anything.
• Omitting the mailto fallback. While the HTTPS URL handles one-click, a mailto: URI provides a fallback for email clients that do not support RFC 8058. Include both.

Deliverability Impact

• Gmail/Yahoo mandate. Bulk senders (5,000+ messages/day) must implement RFC 8058. Non-compliance leads to increased spam filtering and potential rejection. This is the single most impactful deliverability requirement introduced in recent years.
• Reduced spam complaints. One-click unsubscribe provides a frictionless alternative to "Report Spam." Users who can easily opt out do not need to complain, directly lowering your complaint rate.
• Positive reputation signal. Properly implemented one-click unsubscribe tells mailbox providers you are a responsible sender who respects user preferences. This contributes to positive sender reputation.
• User experience. Recipients see a clear, prominent "Unsubscribe" link in Gmail, Yahoo Mail, and Apple Mail. This builds trust — users are more likely to engage with email when they know they can easily stop it.
• Processing speed matters. Gmail may verify that the POST endpoint actually works by testing it. If your endpoint is slow or unreliable, the one-click button may not appear. Keep response times under 1 second.

Related RFCs