Implementing one-click unsubscribe (RFC 8058) correctly

Gmail and Yahoo require bulk senders to support one-click unsubscribe on marketing and subscribed messages. The mechanism is defined in RFC 8058 and takes two headers, one DKIM signature and one endpoint, but each piece has details that commonly go wrong.

This guide builds it from the headers down to the handler.

What one-click unsubscribe is#

The older List-Unsubscribe header (RFC 2369) lets a message advertise how to unsubscribe, typically with a URL or a mailto: address. The problem was the URL: mailbox providers could not safely fetch it automatically, because a plain GET to a link might trigger anything, and security scanners that pre-fetch links would unsubscribe people by accident.

RFC 8058 fixes that by defining a POST-based flow. The message says, in effect, "send an HTTP POST with this exact body to this URL and the recipient is unsubscribed, no further interaction needed." Mailbox providers then show their own unsubscribe button near the sender name, and when the user clicks it, the provider makes the POST on their behalf.

The two headers#

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

Rules from RFC 8058:

• List-Unsubscribe must contain an HTTPS URI. A mailto: URI alone does not qualify for one-click. Including a mailto: alongside the HTTPS URI is allowed and gives clients a fallback.
• List-Unsubscribe-Post must contain exactly List-Unsubscribe=One-Click.
• The URI must identify the recipient and list on its own. The provider will not send cookies or ask the user anything, so the URL needs an opaque token that maps to the subscription.
• Both headers must be covered by a valid DKIM signature. RFC 8058 requires that the message have a valid DKIM signature covering at least List-Unsubscribe and List-Unsubscribe-Post. Without that, a receiver cannot trust that the URL was put there by the sender.

Step 1: generate a token per recipient and list#

The token should be:

• Unguessable, so nobody can unsubscribe other people by iterating values.
• Specific to one recipient and one list or category.
• Long-lived, since people unsubscribe from messages weeks or months later.

Two common approaches work well. One is a random identifier stored in a table that maps it to the subscription. The other is a signed value, such as an HMAC over the subscriber ID and list ID with a server secret, which needs no lookup table but must be verified carefully.

import hmac, hashlib, base64

def unsub_token(subscriber_id: str, list_id: str, secret: bytes) -> str:
    msg = f"{subscriber_id}:{list_id}".encode()
    sig = hmac.new(secret, msg, hashlib.sha256).digest()[:16]
    return base64.urlsafe_b64encode(msg + b"." + sig).decode().rstrip("=")

Avoid putting a plain email address in the URL. It leaks the address into logs and referrers and makes tokens guessable.

Step 2: add the headers when building the message#

Insert both headers before DKIM signing happens. If you sign in your own code, make sure both header names are in the h= list. If your email provider signs for you, check the documentation: some providers add these headers themselves, and some let you set them per message. Verify on a real message that both appear in the DKIM signature's h= tag.

The visible unsubscribe link in the message body is a separate requirement. Gmail and Yahoo also expect a clearly visible link, and it can point to a preferences page that requires a click, since a human is using it.