The List-Unsubscribe header gives mailbox providers a machine-readable way to let recipients stop promotional email without hunting through a message footer. It is a small piece of email infrastructure with an outsized effect on recipient trust, complaint rates, and bulk-sender compliance.

What a List-Unsubscribe header is

List-Unsubscribe is an email header defined by RFC 2369. Unlike a visible unsubscribe link in the HTML or plain-text body, it lives in the message headers that email clients and mailbox providers inspect before or while displaying a message.

A receiving provider can use the header to surface an unsubscribe control in its own interface. Depending on the recipient’s mailbox provider and client, that may appear near the sender name, in a message menu, or in a subscription-management view. The exact placement is controlled by the mailbox provider, not by the sender.

The header can contain one or more unsubscribe mechanisms:

A mailto: URI, which asks the recipient’s mail client to compose an opt-out email.
An HTTPS URL, which leads to an unsubscribe page.
An HTTPS URL paired with RFC 8058’s List-Unsubscribe-Post header, which supports a true machine-to-machine one-click unsubscribe request.

A basic header using both mail and web methods looks like this:

List-Unsubscribe: <mailto:unsubscribe@example.com?subject=unsubscribe>, <https://email.example.com/unsubscribe/7c8f4a9d>

The angle brackets matter. RFC 2369 represents unsubscribe destinations as URLs enclosed in < and >, with multiple options separated by commas. A receiving service may choose the method it supports.

The header is primarily for mailing-list, promotional, newsletter, and subscription traffic. It is not a substitute for a visible unsubscribe link, a consent record, or a durable suppression system. Think of it as an additional opt-out path that should lead to the same underlying preference and suppression decisions as every other unsubscribe channel.

List-Unsubscribe versus one-click unsubscribe

These terms are often used interchangeably, but they describe related rather than identical features.

List-Unsubscribe is the discovery mechanism

The List-Unsubscribe header advertises where an unsubscribe request can be sent. It can advertise a mailto: address, an HTTPS URL, or both. A standard web URL may require the recipient to visit a page and confirm the change.

For example:

List-Unsubscribe: <https://email.example.com/preferences/unsubscribe?token=opaque-token>

That is a valid list-unsubscribe URL. But a security scanner that follows the URL must not accidentally unsubscribe the recipient. The safe design is for a normal browser visit to display a confirmation page or preference center rather than immediately applying the opt-out.

RFC 8058 provides the one-click signal

RFC 8058 introduced List-Unsubscribe-Post, a second header that tells a mailbox provider the HTTPS unsubscribe endpoint supports an automated POST request. This is the modern one-click pattern used by major mailbox providers for qualifying subscription mail.

The normal header pair is:

List-Unsubscribe: <https://email.example.com/unsubscribe/7c8f4a9d>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

When a mailbox provider offers its own unsubscribe control and the recipient uses it, the provider can send a request like this:

POST /unsubscribe/7c8f4a9d HTTP/1.1
Host: email.example.com
Content-Type: application/x-www-form-urlencoded

List-Unsubscribe=One-Click

The receiving endpoint should validate the opaque token, apply the relevant unsubscribe immediately, and return a successful HTTP response such as 200 OK or 204 No Content. It must not require a session, password, CAPTCHA, marketing survey, or another confirmation click.

This distinction solves a real safety problem. Mail-security systems routinely fetch URLs to inspect them. If a plain GET URL directly unsubscribed a recipient, automated scanners could create unintended opt-outs. With the RFC 8058 pattern, a regular browser GET can safely show an explanatory page, while only the specifically formatted POST performs the automated one-click action.

Why list unsubscribes matter for deliverability

An unsubscribe is usually better than a complaint. Someone who no longer wants marketing email has several choices: ignore it, delete it, mark it as spam, block the sender, or unsubscribe. Of those outcomes, an easy, correctly handled unsubscribe is often the healthiest for the sender-recipient relationship.

Complaint signals can contribute to poor reputation and reduced inbox placement. They can also indicate that targeting, frequency, expectations, or list acquisition practices need attention. A List-Unsubscribe header does not solve those underlying problems, but it gives dissatisfied recipients a straightforward alternative to the spam button.

Mailbox providers now treat opt-out handling as a technical and operational quality signal. For example, Gmail’s sender guidelines require bulk senders to make it easy for recipients to unsubscribe, while its documented bulk-sender threshold is roughly 5,000 messages to personal Gmail accounts in a 24-hour period. Gmail also notes that messages from the same primary domain count together, including subdomains. Yahoo similarly requires an implemented list-unsubscribe header for promotional or marketing mail and distinguishes that requirement from transactional mail.

That means unsubscribe implementation belongs in the same category as authentication, complaint handling, bounce management, and list hygiene. It is not just a footer-design task.

The visible unsubscribe link still matters

Do not remove the visible unsubscribe link from the message body because you have implemented headers. A recipient may use an email client that does not expose native list-unsubscribe controls. They may view the message in a web archive, forward it, print it, or receive it after a provider has not elected to show the header-driven option.

Place a clear unsubscribe or manage-preferences link in both the HTML and plain-text versions of promotional email. A preference center can be useful, but the path to stop the category of email that was sent should be prominent and uncomplicated.

A strong message footer commonly offers both options:

Manage email preferences: https://email.example.com/preferences/opaque-token
Unsubscribe from product updates: https://email.example.com/unsubscribe/opaque-token

The header and body links should be backed by the same source of truth. If a header POST writes to one database and the footer form writes to another, suppression gaps will eventually occur.

When to add List-Unsubscribe headers

Add the List-Unsubscribe header to email that recipients reasonably experience as recurring, promotional, or subscription-based. Typical examples include newsletters, product announcements, event invitations, marketing campaigns, content digests, re-engagement messages, and sales promotions.

Use judgment for mixed messages. A receipt that also contains a large promotional module may be legally transactional in one jurisdiction but still feel promotional to a recipient. If a message is recurring or contains meaningful marketing material, a category-level opt-out can reduce complaints and make recipient expectations clearer.

Usually, do not attach list-unsubscribe headers to messages that must reach users for operational or security reasons, such as:

Password resets and multi-factor authentication codes.
Account-security alerts.
Purchase receipts, invoices, and essential delivery updates.
Service outage notices.
Contractually required or legally required notices.

That does not mean transactional streams should be used as a loophole for campaigns. Keep marketing and transactional traffic logically separated. Use distinct message types, templates, audiences, and ideally distinct sending subdomains or From addresses when the scale and program justify it.

Model subscriptions by purpose

A recipient who leaves a weekly product-newsletter list has not necessarily opted out of billing email, password-reset mail, or a separate event series. Your data model should preserve the scope of each choice.

A practical subscription model might include:

Subscription category	Example messages	Default unsubscribe effect
marketing	promotions, launches, newsletters	suppress marketing category
product updates	release notes, feature announcements	suppress product-updates category
events	webinars, local events, conference notices	suppress events category
transactional	receipts, verification, security alerts	no marketing unsubscribe action
global marketing suppression	all non-essential commercial email	suppress every marketing category

The List-Unsubscribe endpoint should normally unsubscribe the recipient from the mailing list or category represented by that specific message. A preference center can offer a global marketing opt-out as an additional choice, but silently turning a list-level request into an account-wide opt-out can create reporting confusion and prevent recipients from receiving categories they still value.

How to implement the header correctly

A reliable implementation has four layers: per-recipient identification, message-header construction, an HTTPS endpoint, and durable suppression propagation.

1. Create an opaque, recipient-specific token

Do not put a raw email address, internal numeric user ID, or easily reversible value in the unsubscribe URL. URLs can appear in logs, analytics systems, forwarded messages, browser history, and security-scanner records.

Instead, issue a random opaque token. On the server side, map that token to the recipient, subscription category, tenant or workspace when applicable, and message or campaign context. A token should have enough entropy to resist guessing; a cryptographically secure random value is appropriate.

For example, the URI can be short and non-descriptive:

https://email.example.com/u/eyJraWQiOiJrMiIsIm4iOiI4aHJ4In0.signature

The application can use either a lookup token stored in a database or a signed token. A database-backed token makes revocation and auditing simple. A signed token can reduce lookup requirements, but it must include expiry and key-rotation handling and should not expose personal data in readable form.

2. Set headers on each qualifying message

For RFC 8058 one-click support, set an HTTPS list-unsubscribe URI and the one-click signal:

List-Unsubscribe: <https://email.example.com/u/opaque-recipient-token>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Optionally include a mailto fallback as a second list-unsubscribe option:

List-Unsubscribe: <https://email.example.com/u/opaque-recipient-token>, <mailto:unsubscribe@example.com?subject=unsubscribe>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

The web URL should be unique to the recipient and list scope. A generic URL such as https://example.com/unsubscribe cannot identify who should be unsubscribed without asking for more information, which defeats the automated one-click flow.

When using an email provider’s REST API, add these as message headers only if the provider permits custom headers and does not overwrite the relevant fields. When sending via SMTP relay, add them as standard Internet message headers before the blank line that separates headers from the body.

For a general overview of SMTP and API message construction, consult the platform’s email API reference and setup guides. The important implementation principle is provider-independent: inspect the final received message source to confirm that the headers survived template rendering, API serialization, relay processing, and any downstream routing.

3. Accept unauthenticated HTTPS POST requests safely

The endpoint must work without the recipient being logged into your product. Mailbox providers, not the recipient’s browser session, initiate the request. Requiring authentication or cookies will break the flow.

The endpoint should:

Require HTTPS and use a valid TLS certificate.
Read the opaque token from the URL path or query string.
Accept the form field List-Unsubscribe=One-Click for POST requests.
Validate the token and its intended list scope.
Write the suppression durably and idempotently.
Return a fast success response.
Record an audit event without storing more personal data than necessary in request logs.

Idempotency is essential. A recipient, provider, retrying network component, or test system may submit more than one request. Repeating the same request should leave the recipient unsubscribed and return success, not produce an error or toggle their preference back on.

A simplified endpoint contract could look like this:

POST /u/{token}
Content-Type: application/x-www-form-urlencoded

List-Unsubscribe=One-Click

Suggested outcomes:

200 OK or 204 No Content: token recognized and opt-out recorded, including an already-recorded opt-out.
400 Bad Request: malformed request body when the endpoint cannot interpret it.
404 Not Found: token is unknown or expired, though returning a generic success response can reveal less about token validity.
405 Method Not Allowed: unsupported HTTP method, provided POST remains enabled.
429 Too Many Requests: only if rate limiting is carefully designed not to block legitimate mailbox-provider requests.
500, 502, 503, or 504: a genuine temporary failure. Monitor these aggressively because they may prevent provider-driven opt-outs.

Avoid redirect chains. A mailbox provider may not follow them in the way a browser does, and every extra network hop creates another failure point. Serve the one-click endpoint directly from the advertised HTTPS URL.

4. Propagate the suppression before the next send

An unsubscribe endpoint is useful only if every sending system honors it. That includes your campaign application, customer-data platform, CRM syncs, batch jobs, background queues, and any separate transactional or marketing provider that may send the same category of mail.

Store at least:

Recipient identifier or normalized email address.
Subscription category or list identifier.
Suppression scope, such as list-level or global marketing.
Timestamp and source, such as header one-click, footer link, support request, or complaint feedback loop.
The campaign or message context where available.
A reason code that supports reporting without exposing unnecessary details.

Before sending a promotional message, evaluate suppression at send time. Do not rely solely on a nightly export because a recipient could unsubscribe between the export and a queued campaign. For high-volume systems, cache suppression decisions carefully but choose a cache lifetime that cannot create a long window for unwanted sends.

Mailto, HTTPS GET, and HTTPS POST compared

Each opt-out method has a role, but they have different reliability characteristics.

Mailto unsubscribe

A mailto: URI is widely understood and can be useful as a fallback:

List-Unsubscribe: <mailto:unsubscribe@example.com?subject=unsubscribe>

Its drawbacks are operational. The recipient’s mail client may open a compose window, the sender may receive a blank or altered subject, and an inbox or automation system must parse and process the request. It is difficult to know which subscription category applies unless the message includes a signed identifier in the mailto address or query string.

If you support mailto, route it to a monitored and automated workflow. Do not make people wait for a manual support inbox review. Treat received mailto requests as opt-out requests even if their formatting is imperfect.

HTTPS GET unsubscribe page

A visible link can safely use an HTTPS GET request to open a preference page:

https://email.example.com/preferences/opaque-token

The page may show the associated address in a privacy-conscious way, explain which category is affected, and offer a button to confirm the action. This interaction is initiated in a browser by a human, so it can present choices that a one-click POST endpoint cannot.

Do not cause an irreversible opt-out merely from opening the GET URL. Link scanners and prefetchers can request it.

HTTPS POST one-click unsubscribe

The RFC 8058 POST flow is best for provider-native unsubscribe actions. It is automatic, does not depend on the recipient’s session, and avoids accidental opt-outs caused by URL prefetching when implemented correctly.

Use the POST endpoint for the immediate list-level action. Use the browser page for human-readable confirmation, preference management, and optional explanation.

Authentication and DNS prerequisites that support trust

List-Unsubscribe headers are not DNS records. You do not publish them in a zone file; you include them in individual email messages. However, mailbox providers evaluate headers in the wider context of sending identity, authentication, and reputation.

For promotional mail, configure SPF, DKIM, and DMARC correctly. Here are valid DNS syntax examples using documentation-style domains and values that must be replaced for a real deployment:

; SPF at the organizational sending domain
example.com. IN TXT "v=spf1 ip4:192.0.2.0/24 -all"

; DKIM public key at the selector hostname
s1._domainkey.example.com. IN TXT "v=DKIM1; k=rsa; p=BASE64_PUBLIC_KEY"

; DMARC policy and aggregate-report address
_dmarc.example.com. IN TXT "v=DMARC1; p=none; rua=mailto:dmarc@example.com; adkim=s; aspf=s"

The 192.0.2.0/24 range is reserved for documentation; it is not a real sending network. In production, use the sending service’s documented SPF authorization mechanism or your actual authorized sending IP addresses. DKIM’s p= value must be the actual base64-encoded public key generated for the corresponding private signing key.

For bulk Gmail traffic, SPF and DKIM authentication, DMARC, valid forward and reverse DNS, TLS, and controlled complaint rates are all part of sender requirements. Authentication alignment matters because it helps a mailbox provider tie the visible From domain to the domain authorized by SPF or DKIM under DMARC.

A practical DNS and authentication checklist is:

The From domain exists and has valid DNS.
The envelope sender or return-path domain is authorized by SPF where SPF is used.
DKIM signatures validate after sending.
The visible From domain aligns with SPF or DKIM for DMARC.
A DMARC record exists at _dmarc.example.com.
Your sending IP has working forward-confirmed reverse DNS when you control the IP.
SMTP transmission uses TLS where supported and required.

Use MXToolbox to inspect DNS records and reverse-DNS configuration, and inspect Authentication-Results in a received message to see how the recipient provider evaluated SPF, DKIM, and DMARC. Authentication will not force an inbox UI to show an unsubscribe control, but poor authentication can undermine the trust and reputation conditions under which mailbox providers make those decisions.

Testing a List-Unsubscribe implementation

Testing must cover the final received message, not merely the code that builds it. Email systems can modify headers, fold long lines, replace templates, or block custom fields after your application hands the message to an API or SMTP relay.

Inspect raw message headers

Send a test message to accounts at more than one mailbox provider. Open the raw source or original message view and check for:

List-Unsubscribe: <https://email.example.com/u/...>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Confirm these details:

The header name is spelled exactly as shown.
The URL is HTTPS.
Angle brackets surround each URI.
The URL contains an opaque recipient-specific token.
List-Unsubscribe-Post appears on promotional messages.
The headers are absent from message types that should not carry them.
The same recipient receives a URL appropriate to the list or category being sent.

Do not use only your provider’s sent-message preview. The received raw source is the authoritative artifact.

Test the one-click endpoint directly

In a non-production environment or with a disposable test recipient, use curl to emulate the basic POST shape:

curl -i -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data "List-Unsubscribe=One-Click" \
  "https://email.example.com/u/TEST_TOKEN"

Verify that the response is successful, the intended suppression is recorded, and subsequent marketing sends exclude the recipient. Repeat the request to confirm idempotency. Then make a browser GET request to the same URL and verify that it does not silently trigger an unsubscribe.

Test failure paths too. Expired, altered, and unknown tokens should not expose recipient data. If your endpoint depends on a database, simulate a temporary database failure and ensure monitoring alerts your team before a sustained outage causes unresolved requests.

Test the rendered message and deliverability posture

Tools such as mail-tester.com can help inspect message structure, authentication, and content signals. It is useful for catching obvious setup errors, but it does not replace testing with actual recipient mailbox providers or reviewing your own event logs and suppression records.

For each release that touches email sending, test:

A campaign message with headers and a visible footer link.
A transactional message without marketing opt-out headers.
A recipient already suppressed from the relevant category.
A recipient globally suppressed from marketing.
A mailto fallback request, if you provide one.
One-click POST handling, including duplicate submissions.
SPF, DKIM, and DMARC results in the delivered message.

Common implementation mistakes

Treating an unsubscribe as a failed delivery

An opt-out is a recipient preference, not a bounce. Do not add it to hard-bounce metrics, retry it as though a transport failed, or remove it from reports. Keep unsubscribe rates distinct from delivery failures, blocks, complaints, and deferrals.

SMTP codes describe mail transfer outcomes, not unsubscribe outcomes. For instance, 250 means an SMTP server accepted a message at that stage; it does not prove that the recipient read it. A 451 response is generally temporary and may be retried with backoff. A 550-class rejection is generally permanent for that attempt and should not be retried blindly. These transport signals should feed your delivery pipeline, while header-driven opt-outs should feed your suppression pipeline.

Using a generic unsubscribe URL

A generic URL forces the provider or recipient to identify the subscriber later. For a one-click POST, the endpoint needs a secure way to determine both the recipient and the relevant list from the request alone. Use a per-recipient token.

Letting a GET request unsubscribe immediately

This is one of the most damaging mistakes because automated scanners may follow links. Keep the automated action behind the RFC 8058 POST flow; let the browser GET path display a safe confirmation or preference page.

Requiring login, CAPTCHA, or a survey

A mailbox-provider POST will not have the recipient’s browser session. Any extra interaction breaks one-click behavior. You can offer optional feedback after applying the opt-out, but never make feedback a condition of honoring it.

Applying the wrong suppression scope

If a product newsletter unsubscribe stops invoices, security alerts, and password-reset mail, users may lose important notices. If a global marketing unsubscribe stops only one small campaign, users will keep receiving unwanted mail. Store scope deliberately and apply it consistently.

Failing to synchronize downstream systems

A sender may have separate systems for lifecycle campaigns, support communications, CRM messages, and product announcements. If only one system checks the suppression table, the recipient will keep receiving messages from the others. Centralize suppression decisions or distribute them through a reliable event stream with monitoring and reconciliation.

Assuming every client will show the native control

Mailbox providers decide whether, where, and when to display an unsubscribe UI. Correct headers are necessary for standards support and may be required for applicable bulk-sender rules, but they do not guarantee a particular visual treatment in every inbox. Keep the body link visible regardless.

Operational reporting and monitoring

A mature unsubscribe program measures more than a single opt-out percentage. Watch trends by list, campaign, acquisition source, send frequency, audience segment, and message type.

Useful metrics include:

Unsubscribe rate per delivered message.
Complaint rate per delivered message.
Time from unsubscribe request to durable suppression.
Number of messages attempted after suppression, which should be zero or explainable only by unavoidable in-flight processing.
One-click endpoint HTTP success and error rates.
Token-validation failures and unusual request patterns.
Preference-center changes by category.
Re-subscribe events and the consent source for those events.

A sudden increase in opt-outs is not automatically bad. It may indicate that a new campaign reached an audience that is no longer interested, that the copy clearly set expectations, or that an unsubscribe mechanism finally became easy to use. Compare it with complaint rate, engagement, conversion quality, and downstream retention before deciding what changed.

The more concerning pattern is rising complaints alongside low unsubscribe usage. That can suggest that recipients cannot find the opt-out, do not trust it, receive email they did not expect, or are overwhelmed by frequency.

A production-ready implementation checklist

Before enabling one-click unsubscribe on a live marketing stream, verify the following:

Conclusion

The List-Unsubscribe header is simple to add but easy to implement incompletely. The durable solution is not just two headers: it is a secure recipient token, an RFC 8058 POST endpoint, a visible body link, a category-aware preference model, and a suppression system that every sender respects.

Implement it before bulk volume turns it into an urgent deliverability problem. More importantly, treat every opt-out as useful feedback: the recipient is choosing a lower-friction way to leave, and your infrastructure should make that choice immediate, accurate, and final for the mail category they selected.

FAQ

What is the List-Unsubscribe header?

List-Unsubscribe is an email header that provides a machine-readable mailto address, web URL, or both for recipients to opt out of a mailing list. Mailbox providers can use it to offer an unsubscribe control outside the message body.

Is List-Unsubscribe the same as one-click unsubscribe?

No. List-Unsubscribe advertises an opt-out method. RFC 8058 one-click unsubscribe adds List-Unsubscribe-Post: List-Unsubscribe=One-Click and an HTTPS endpoint that accepts an automated POST request without further recipient interaction.

Should transactional emails include List-Unsubscribe headers?

Usually no for essential transactional messages such as password resets, receipts, security notifications, and service alerts. Promotional, newsletter, and subscription email should have easy opt-out paths. Keep mixed transactional and marketing content under careful review.

Do I need both a header and an unsubscribe link in the email body?

Yes. The header supports mailbox-provider interfaces, while the visible HTML and plain-text link works across clients and gives recipients a direct, understandable path to manage preferences.

How quickly should an unsubscribe take effect?

Make the suppression effective immediately in your own systems. Major mailbox-provider guidance for bulk senders expects unsubscribe requests to be honored within two days, but there is no operational benefit to waiting when your endpoint and sending workflow can apply the preference at once.

List Unsubscribes: How to Implement One-Click Opt-Outs