One-Click Unsubscribe and List-Unsubscribe Headers

When recipients cannot find a way to stop your emails, they use the spam button. A spam complaint harms your sender reputation far more than an unsubscribe does. List-Unsubscribe headers give mailbox providers a reliable way to show their own unsubscribe option in the interface, and one-click unsubscribe is now a requirement for bulk senders at Gmail and Yahoo.

What the Requirement Says

Senders of 5,000 or more messages a day to Gmail or Yahoo must:

• Include one-click unsubscribe headers on marketing and subscribed messages.
• Include a clearly visible unsubscribe link in the message body.
• Honor unsubscribe requests within two days.

Transactional messages such as receipts, password resets and security alerts are not covered by the one-click rule. Microsoft recommends a functional unsubscribe link for high-volume senders as well.

The Two Headers

One-click unsubscribe uses two email headers together.

List-Unsubscribe: <https://example.com/unsubscribe?id=abc123>, <mailto:unsubscribe@example.com?subject=unsubscribe>

List-Unsubscribe-Post: List-Unsubscribe=One-Click

The first header lists where an unsubscribe request can be sent: an HTTPS address, a mailto address, or both. The second header, defined in RFC 8058, tells the mailbox provider that the HTTPS address accepts a one-click request.

How One-Click Works

When a recipient clicks the provider's unsubscribe button, the provider sends an HTTP POST request to the HTTPS address in the header, with the body List-Unsubscribe=One-Click. Your server must process that request and unsubscribe the recipient without any further action from them.

The mechanism uses POST for a reason. Security scanners and link previews often open links in emails automatically with GET requests. If a simple visit to a link unsubscribed people, scanners would unsubscribe your whole list.

Implementation Rules

For one-click to be honored:

• The List-Unsubscribe header must contain at least one HTTPS address.
• The endpoint must accept a POST request and act on it.
• It must not require a login, a confirmation page or any extra input.
• It should not redirect.
• The address should contain an opaque identifier for the recipient and the list, so the request cannot be forged or guessed.
• Both headers must be covered by a valid DKIM signature.

Including a mailto option as well is good practice, because some mailbox providers still use it.

The Body Link

The header does not replace the unsubscribe link in the message. You need both. The body link may lead to a preference center that offers alternatives, such as fewer emails or different topics. The header mechanism must unsubscribe immediately.

How Providers Use the Headers

Gmail shows an unsubscribe link next to the sender name for senders it trusts. Yahoo and Apple Mail show similar controls. Display is not guaranteed. Providers tend to show the option only for senders with a reasonable reputation, so a missing button does not always mean your headers are wrong.

Gmail also offers to unsubscribe users when they report a message as spam, and may suggest unsubscribing from senders they have not opened in a while.

Checking Your Setup

Most email service providers add these headers automatically for marketing mail. Verify it instead of assuming.

1. Send a campaign to a Gmail address.
2. Open the message and choose Show original.
3. Search the headers for List-Unsubscribe and List-Unsubscribe-Post.
4. Confirm that the h= field of the DKIM signature lists both headers.
5. Click the provider's unsubscribe control and confirm that the address is suppressed.

Google Postmaster Tools also reports one-click unsubscribe in its compliance status dashboard.

Honoring Requests

Processing the request is only half of the obligation. Once someone unsubscribes:

• Stop sending within two days. Immediate suppression is better.
• Apply the opt-out across the mail stream they left, wherever that list is stored.
• Sync suppressions between systems, so a contact removed in one tool is not mailed from another.
• Never reimport unsubscribed addresses.

Common Mistakes

• Sending only a mailto address. One-click requires HTTPS.
• Adding List-Unsubscribe without List-Unsubscribe-Post.
• Pointing the header at a preference page that needs a second click.
• Requiring a login to unsubscribe.
• Leaving the headers out of the DKIM signature.
• Adding the headers to marketing mail from one platform but not from another.
• Hiding the body link in small, low-contrast text.

Why It Helps Deliverability

Every recipient who leaves through an unsubscribe is one who did not report you as spam. Complaint rate is the measure Gmail enforces most strictly, with a target below 0.1% and a hard line at 0.3%. A list that is easy to leave is smaller, more engaged and far easier to deliver to.