What Is List-Unsubscribe? One-Click Unsubscribe (RFC 8058) Explained

List-Unsubscribe is a message header that tells the mail app how a recipient can stop receiving a mailing, so the app can show a native Unsubscribe link next to the sender name. RFC 8058 adds a second header, List-Unsubscribe-Post, which lets the app unsubscribe with a single HTTPS POST and no confirmation page. Since 2024, Gmail and Yahoo require one-click unsubscribe on bulk mail and expect requests to be honoured within two days.

Quick summary

• The sender includes a unique, unguessable token per recipient in the List-Unsubscribe URL.
• The mail app displays an Unsubscribe control when both headers are present and the message is DKIM-authenticated.
• The user clicks once. The app POSTs to the URL with the body List-Unsubscribe=One-Click, without opening a browser.
• The server must process the POST immediately and return a 2xx. No login, no confirmation, no survey.
• Some apps use the mailto: form instead, sending an email to the address; the sender must handle both.

The two headers

List-Unsubscribe: <https://yourdomain.com/unsub?u=a1b2c3>, <mailto:unsubscribe@yourdomain.com?subject=unsub-a1b2c3>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

When the user clicks Unsubscribe, the mail app sends:
POST /unsub?u=a1b2c3 HTTP/1.1
Host: yourdomain.com
Content-Type: application/x-www-form-urlencoded

List-Unsubscribe=One-Click

How one-click works

1. The sender includes a unique, unguessable token per recipient in the List-Unsubscribe URL.
2. The mail app displays an Unsubscribe control when both headers are present and the message is DKIM-authenticated.
3. The user clicks once. The app POSTs to the URL with the body List-Unsubscribe=One-Click, without opening a browser.
4. The server must process the POST immediately and return a 2xx. No login, no confirmation, no survey.
5. Some apps use the mailto: form instead, sending an email to the address; the sender must handle both.

Rules that trip people up

• The URL must be HTTPS and must not require any interaction. A page that asks "are you sure?" fails the requirement.
• A GET to the same URL should not unsubscribe, because link scanners at corporate gateways follow links automatically. Only the POST with the One-Click body should act.
• The headers must be inside the DKIM-signed header set (h= tag) or apps ignore them.
• The token must identify the recipient without exposing their address or letting someone unsubscribe others.
• Bulk means roughly 5,000 messages per day to Gmail, but the header is good practice on every marketing message regardless of volume.

How to check your headers

• Send a campaign to a Gmail test address and look for the Unsubscribe link beside the sender name at the top of the message.
• Open Show original and confirm both headers are present and that the DKIM h= list includes list-unsubscribe.
• Send a POST to your endpoint with curl -X POST -d "List-Unsubscribe=One-Click" and confirm the recipient is removed.
• Watch Google Postmaster Tools spam rate; it usually falls once unsubscribing is easier than reporting.

Where List-Unsubscribe does not belong

Transactional mail such as receipts, password resets, shipping updates and replies to a customer question should not carry the header, because the recipient cannot opt out of a receipt and an Unsubscribe link on one confuses people. Apply it to newsletters, promotions and any recurring mailing someone signed up for. Keep those two kinds of mail on separate addresses so a marketing complaint never touches your invoices.

List-Unsubscribe and OquMail

OquMail mailboxes and the transactional send API are built for one-to-one and transactional mail, which is exactly the traffic that does not need the header. If you run a newsletter, use a tool designed for bulk sending on a subdomain such as news.yourdomain.com, and keep your conversations, receipts and API notifications on OquMail with the same domain identity. The DMARC record OquMail guides you to publish covers both, and relaxed alignment lets the subdomain align with your main domain.

Common questions

Is the header required by law?

Laws such as CAN-SPAM, GDPR and CASL require a working opt-out, not this specific header. Gmail and Yahoo require the header as a condition of delivery for bulk senders, which in practice is stricter.

Can I use only the mailto: form?

For the one-click requirement, no. RFC 8058 needs the HTTPS URL plus List-Unsubscribe-Post. Including mailto: as well is recommended for older apps.

Will adding the header make more people unsubscribe?

Some, and that is good. Those people would otherwise mark you as spam, which costs far more than a lost subscriber.