How To Add One Click Unsubscribe With List-Unsubscribe Headers

One-click unsubscribe is a mail-header based opt-out that lets inboxes show a native Unsubscribe control near the sender name, so recipients can leave cleanly without hunting for a footer link. To make it work, send both a List-Unsubscribe header and a List-Unsubscribe-Post header set to List-Unsubscribe=One-Click, pointing to an HTTPS endpoint that can immediately remove the address. Follow RFC 8058 basics: sign the headers with DKIM, use an opaque identifier instead of a raw email address, and treat the POST as the action that completes the unsubscribe. The tricky part is that tiny formatting and endpoint details decide whether clients trust it or quietly ignore it.

List-Unsubscribe headers and the inbox unsubscribe button

What mailbox providers use it for

Mailbox providers look at List-Unsubscribe headers to understand how a recipient can opt out of a mailing list. When the headers are present and trusted, providers may surface an inbox-level unsubscribe control (often near the From name or message header area). That gives the recipient a fast, recognizable way to stop messages without scrolling for a footer link.

For true “one-click” behavior, providers can use the HTTPS URL in your List-Unsubscribe header and send an HTTPS POST when the user confirms the action. That flow is defined in RFC 8058. It also requires that the List-Unsubscribe and List-Unsubscribe-Post headers are covered by a valid DKIM signature. If the message is not authenticated or the headers look suspicious, providers may choose not to display the button.

The key idea is simple: the provider is trying to give users a safe, low-friction opt-out that does not train them to click random links in the message body.

Benefits for deliverability and complaint reduction

A visible inbox unsubscribe button usually means fewer “this is spam” clicks. That matters because spam complaints are a strong negative signal for sender reputation. When people can leave in one or two taps, they are more likely to unsubscribe than to report.

List-Unsubscribe headers also reduce support burden. Fewer replies like “please remove me” and fewer manual removals. They can improve list hygiene over time, because disengaged recipients have an easy exit instead of staying on your list and dragging down opens, clicks, and overall engagement signals.

For teams sending through Mailscribe, this is one of the simplest technical upgrades that improves user experience while aligning your sending practices with how modern inboxes expect bulk and marketing email to behave.

List-Unsubscribe header formats: mailto vs HTTPS URL

When to include both methods

List-Unsubscribe supports two common methods:

• mailto: the mailbox provider generates an email to an unsubscribe address you control.
• HTTPS URL: the mailbox provider (or the user’s client) opens a web unsubscribe link, and for one-click unsubscribe it can send an HTTPS POST.

In practice, including both is often the safest choice. Some clients understand mailto but not HTTPS. Others prefer HTTPS because it is easier to automate and can support true one-click behavior when you also add List-Unsubscribe-Post.

Use mailto when you need a fallback for older clients, or when your compliance process requires an email-based request path. Use HTTPS when you can support an immediate, automated unsubscribe on your side. If you only choose one, HTTPS is usually the better long-term option for modern providers, as long as your endpoint is reliable and fast.

One important rule: the HTTPS URL should not expose the recipient’s email address. Use an opaque token or subscriber ID.

Common header syntax and examples

The List-Unsubscribe header is a comma-separated list of angle-bracketed URIs. Typical examples:

List-Unsubscribe: <mailto:unsubscribe@example.com?subject=unsubscribe> List-Unsubscribe: <https://mailer.example.com/unsubscribe/u/AbC123xYz> List-Unsubscribe: <mailto:unsubscribe@example.com?subject=unsubscribe>, <https://mailer.example.com/unsubscribe/u/AbC123xYz>

A few syntax tips that prevent painful troubleshooting later:

• Keep it to valid URIs inside < > brackets.
• If you fold the header across lines, start the continued line with whitespace.
• For one-click, the HTTPS URL should be the same destination you are prepared to accept as an automated POST target (paired with your List-Unsubscribe-Post header in the next step).

RFC 8058 one-click unsubscribe: List-Unsubscribe-Post requirements

What “one-click” means for providers

In RFC 8058, “one-click unsubscribe” has a very specific meaning. The inbox can complete the unsubscribe automatically, without sending the reader to a web page to log in, re-enter an email address, or click extra confirmation links.

Mailbox providers do this by sending an HTTPS POST to the HTTPS URL you publish in your List-Unsubscribe header. The POST is the action that performs the opt-out. A normal browser-style GET can still exist for manual unsubscribes, but GET should not silently unsubscribe someone. This split is one reason RFC 8058 exists: it reduces the risk of accidental unsubscribes from link scanners and previews.

Providers must also get user consent before they fire the POST. How they ask (a dialog, a button, a confirmation toast) is up to them, not the standard. You can read the exact behavior in RFC 8058.

Required header values and placement

To qualify as RFC 8058 one-click, you need two headers in the message:

• List-Unsubscribe: must include at least one HTTPS URI (mailto can be included as an extra fallback).
• List-Unsubscribe-Post: must be exactly List-Unsubscribe=One-Click (case and spelling matter, and it is a single key/value pair).

Just as important: the message must have a valid DKIM signature and that DKIM signature must cover both List-Unsubscribe and List-Unsubscribe-Post in the DKIM h= list. If those headers are not DKIM-signed, many providers will refuse to show one-click unsubscribe even if everything else looks right.

Finally, your HTTPS endpoint must not rely on cookies or interactive sessions. The POST has to be enough to identify the recipient and the list and complete the unsubscribe on its own.

Adding List-Unsubscribe headers in SMTP, APIs, and ESPs

Setting custom headers via SMTP

If you send through SMTP, you usually add List-Unsubscribe headers as normal RFC 5322 message headers. Most SMTP libraries let you set custom headers on the MIME message object.

At a minimum, include an HTTPS unsubscribe URL:

List-Unsubscribe: <https://example.com/unsubscribe/t/AbC123xYz> List-Unsubscribe-Post: List-Unsubscribe=One-Click

A few practical rules:

• Put the headers on the top-level message, not inside a MIME part.
• Keep the unsubscribe token opaque. Do not embed the raw email address.
• Make sure your DKIM signing step happens after headers are finalized, so DKIM covers them.

Adding headers via email sending APIs

Most email sending APIs have a “headers” or “custom headers” field where you can pass these values directly. The same formatting rules apply: angle brackets for the URI in List-Unsubscribe, and the exact value List-Unsubscribe=One-Click for List-Unsubscribe-Post.

If your platform distinguishes between “transactional” and “marketing” streams, apply one-click unsubscribe to the stream that represents bulk or marketing mail. Transactional mail often has different expectations and may not be eligible for an unsubscribe button in some inboxes.

Verifying headers in a raw message

Do not trust your application code until you confirm what was actually delivered. Check the raw source of a received email and verify:

• List-Unsubscribe exists and contains the intended HTTPS URL (and optional mailto).
• List-Unsubscribe-Post exists and is spelled exactly.
• Your DKIM-Signature includes both header names in the h= list.
• There is only one effective set of these headers (duplicates can cause clients to ignore them).

In testing, send to a mailbox you control, open the raw headers, and confirm the final wire format matches your intent before rolling out broadly in Mailscribe.

Building a safe unsubscribe endpoint for one-click POST requests

Tokenized unsubscribe links and privacy

Treat your one-click unsubscribe URL as a sensitive identifier. Mailbox providers may fetch it automatically, security tools may scan it, and users may forward messages. For that reason, avoid putting personal data in the URL.

A good pattern is a tokenized unsubscribe link that encodes only what you need to process the request, such as a subscriber ID plus list ID, signed with an HMAC or wrapped as a short-lived JWT. Keep it opaque so it cannot be guessed or enumerated. If you must include IDs, make sure they are not sequential.

Also think about privacy in logs and analytics. Unsubscribe URLs often end up in access logs, CDN logs, and APM traces. If the token can be reversed into an email address, you have effectively leaked PII into systems that were not designed to store it.

Idempotent POST handling and expected responses

Your endpoint should be safe to call more than once. Providers, retries, and network timeouts can create duplicates. Make the POST idempotent: if the recipient is already unsubscribed, return success anyway.

Operationally, aim for:

• Fast response time.
• No redirects for the POST.
• No HTML. No interstitial. No “confirm your email” step.
• A clear success status code.

A typical approach is to accept the POST, validate the token, mark the address unsubscribed for that list, and respond with a simple 200 OK. If the token is invalid or expired, respond with a 400 or 404. Avoid 500 for normal “not found” cases, since it encourages retries.

It is fine to have a separate GET route that shows a human-friendly page (for manual unsubscribes), but keep POST as the direct action.

Logging and audit fields to keep

Keep enough data to prove compliance and troubleshoot issues, without collecting more PII than you need. Useful fields include:

• Timestamp (UTC) and processing duration
• Token identifier or hashed token (not the raw token)
• List or audience ID and sender identity (brand, subaccount, or workspace)
• Result (unsubscribed, already unsubscribed, invalid token)
• HTTP status code returned
• Provider hints like User-Agent (if present) and request IP (store only if your policy allows it)

This level of logging makes it easier to debug “the button shows but nothing happens” reports, and it helps you audit unsubscribe handling inside Mailscribe without turning your logs into a second subscriber database.

Client support: where one-click unsubscribe appears and why

Gmail, Yahoo, Apple Mail, and Outlook behavior

In Gmail, List-Unsubscribe headers can trigger the native Unsubscribe control near the sender name, but it is not guaranteed for every sender. Google ties display to automated eligibility checks, so even correct headers may not show if the message or sender does not meet trust thresholds. Gmail also treats “one-click” as the RFC 8058 flow using an HTTPS URL in the header, not a footer link.

Yahoo Mail supports both mailto (RFC 2369) and RFC 8058 one-click unsubscribes, and it uses these signals for features like its Subscription Hub. If you want the most consistent behavior across Yahoo properties, implement the RFC 8058 pair (HTTPS List-Unsubscribe plus List-Unsubscribe-Post).

In Apple Mail (macOS and iOS), users may see a banner that offers to unsubscribe from mailing lists. In practice, Apple’s unsubscribe action is commonly driven by the mailto method in the List-Unsubscribe header, and HTTPS one-click behavior is less consistent across Apple clients.

With Outlook (especially Outlook on the web and consumer Outlook.com), unsubscribe UI and behavior can vary. Some experiences use a client-side “stop seeing this sender” style action that does not reliably call your List-Unsubscribe endpoint, so you should still make your in-message unsubscribe link clear and functional.

Provider requirements that affect display

A few requirements decide whether the button appears at all:

• RFC 8058 formatting: List-Unsubscribe with an HTTPS URL, plus List-Unsubscribe-Post: List-Unsubscribe=One-Click.
• DKIM coverage: RFC 8058 requires that both headers are included in the DKIM-signed header list, or providers should not offer one-click.
• Marketing vs transactional classification: Google requires one-click unsubscribe for marketing and promotional messages, not typical transactional mail.
• Reputation and user safety checks: Providers may hide the button for senders with poor complaint rates or other risk signals.

Common pitfalls and troubleshooting when the button doesn’t show

Misformatted headers and encoding issues

The most common failure is boring but deadly: the headers are present, but not in a form inboxes will trust.

Watch for these issues:

• Missing angle brackets around the URI. Providers expect <https://...> and <mailto:...>.
• No HTTPS URL in List-Unsubscribe. A footer link is not the same thing, and a mailto-only header will not qualify as RFC 8058 one-click for providers that enforce it.
• Wrong List-Unsubscribe-Post value. It must be exactly List-Unsubscribe=One-Click (spelling and punctuation matter). RFC 8058 defines this as a fixed token.
• Broken header folding. If your MTA wraps long lines, the continuation lines must start with whitespace. Otherwise you can end up with an invalid header.
• Duplicate headers. Two List-Unsubscribe headers (from your app plus your ESP) can cause clients to ignore both.

Authentication and alignment gotchas

Even perfectly formatted headers can be ignored if authentication is weak.

For RFC 8058, the email must have a valid DKIM signature, and both List-Unsubscribe and List-Unsubscribe-Post must be included in the DKIM h= list. If your system signs first and then adds headers later, you will fail this check.

Also make sure your overall authentication is stable: SPF and DKIM passing, plus DMARC alignment for the visible From domain when you use DMARC. Yahoo lists DMARC passing and From alignment as part of its bulk sender requirements.

Transactional vs marketing unsubscribe behavior

Do not expect the inbox button for every message type. Gmail’s guidelines say one-click unsubscribe is required for marketing and promotional messages, and transactional messages are excluded. Gmail also notes that the top-of-message unsubscribe UI appears only after automated eligibility checks.

If you are mixing marketing content into receipts or account alerts, clients may classify the message differently than you intended. Keep promotional mail and transactional mail in separate streams, and apply List-Unsubscribe consistently to the subscribed, marketing stream.