A List-Unsubscribe header gives mailbox providers a standardized way to offer recipients an unsubscribe control outside the email body. For marketing and subscribed mail, the reliable modern implementation is an HTTPS unsubscribe URL paired with the RFC 8058 one-click POST header.

This guide explains what to add, where to add it, how the endpoint should behave, how to test it, and when the header does not belong on a message.

What a List-Unsubscribe header does

List-Unsubscribe is an email message header defined by RFC 2369. It contains one or more URLs that tell a receiving mailbox provider or email client how a recipient can leave a mailing list.

A supporting inbox can use the header to show an unsubscribe control near the sender details, rather than forcing a recipient to find a small footer link. The exact interface is controlled by the mailbox provider, so adding the header does not guarantee that every recipient will see a button. It does give providers a machine-readable, consistent unsubscribe method.

The base header looks like this:

List-Unsubscribe: <https://email.example.com/unsubscribe/abc123>

RFC 2369 also permits multiple alternatives, separated by commas:

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

In practice, the first URL should normally be an HTTPS endpoint for the recipient-specific unsubscribe action. A mailto: URI can be included as a compatibility fallback, but it is not a replacement for RFC 8058 one-click unsubscribe.

A List-Unsubscribe header is useful because it separates the unsubscribe instruction from the visual design of the message. A recipient can still have a clear unsubscribe link in the email footer, but a mailbox provider can also recognize the message as list mail and offer an inbox-level opt-out action.

List-Unsubscribe versus one-click unsubscribe

The terms are related but not interchangeable.

A List-Unsubscribe header is the RFC 2369 mechanism that provides one or more unsubscribe URIs. It can contain an HTTPS link, a mailto: address, or both.

One-click unsubscribe usually refers to the RFC 8058 extension. RFC 8058 adds a second header, List-Unsubscribe-Post, that tells a mailbox provider it can send an HTTP POST request to the HTTPS URL instead of opening the URL in a browser.

Use this pair for subscribed and marketing email:

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

The distinction matters for safety. Some automated systems retrieve URLs in email headers to inspect messages, protect users, or generate previews. If a simple GET request immediately unsubscribed a person, an automated fetch could mistakenly remove them from a list.

RFC 8058 avoids that problem by using an explicit POST signal. The presence of List-Unsubscribe-Post: List-Unsubscribe=One-Click tells a receiving system that the HTTPS URL supports a deliberate one-click POST action.

For a production implementation, think of the two headers as a matched set:

List-Unsubscribe supplies a recipient-specific HTTPS URI.
List-Unsubscribe-Post signals one-click POST support.
A valid DKIM signature covers both headers.
Your endpoint accepts and processes the POST without requiring a login, CAPTCHA, survey, or additional confirmation step.

When you should include the header

Include the List-Unsubscribe header on mail that represents an ongoing subscription or promotional relationship. Typical examples include:

Product newsletters and editorial digests
Marketing campaigns and promotions
Event announcements sent to subscribers
Lifecycle campaigns, such as onboarding tips or re-engagement series
Subscription notices where recipients can opt out of future non-essential messages
Bulk updates from a community, marketplace, or creator

Do not automatically add it to every email your application sends. Password resets, login verification codes, fraud warnings, account-security alerts, purchase receipts, invoices, and service-critical notices generally are not promotional list mail. Giving recipients an unsubscribe control on those messages can create confusion and may suppress communications they still need to receive.

The practical rule is simple: if a recipient can reasonably choose to stop receiving this category of non-essential mail, it is a candidate for List-Unsubscribe. If the message is required to operate an account, complete a transaction, or protect the recipient, do not treat it as a marketing subscription.

Many applications send both categories from the same domain. That is fine, but your sending logic should classify messages before adding headers. Use a campaign or subscription category for marketing mail and a transactional category for operational mail.

The recommended header format

For modern bulk and campaign mail, use an HTTPS URI plus RFC 8058:

List-Unsubscribe: <https://email.example.com/unsubscribe/v1/9b4c2e1a-1b60-4a11-a411-3f7c3e6d7b3e>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

The value inside angle brackets must be a valid URI. Keep it on one logical line, even if your sending library folds the header across physical lines during message serialization.

Use HTTPS, not HTTP

Your unsubscribe URL should use HTTPS. An unsubscribe request is sensitive because it can identify a recipient and alter their communication preferences. HTTPS also matches the RFC 8058 one-click model.

Avoid putting a raw email address, database ID, or other personally identifiable value in the URL. Query strings and paths may end up in application logs, CDN logs, browser history, security tooling, or support screenshots.

Prefer an opaque, high-entropy token that maps to the recipient and subscription scope in your database:

https://email.example.com/unsubscribe/v1/4d1d34e0a0f84de3b8aa3c2f6a1d9e34

A signed token is also common. For example, a token can encode the recipient identifier, list identifier, expiry, and signature. The endpoint verifies the signature before changing preferences. Do not rely on a reversible base64-encoded email address as your only protection; base64 is encoding, not encryption or authorization.

Put the HTTPS method first

RFC 2369 permits multiple URLs. Supporting clients generally choose a method they understand, and the list is ordered by sender preference. Put the preferred HTTPS URI first.

List-Unsubscribe: <https://email.example.com/unsubscribe/v1/4d1d34e0a0f84de3b8aa3c2f6a1d9e34>, <mailto:unsubscribe@example.com?subject=unsubscribe>

Do not insert whitespace inside < and >, inside the URL, or around the URI itself. The comma separates alternatives; it is not part of either URI.

Treat mailto as a fallback, not the primary design

A mailto: option can help older software or recipients who prefer an email-based unsubscribe route. However, mailto-based unsubscribe flows can require a configured mail client, may create manual support work, and cannot provide the RFC 8058 POST behavior expected for a true one-click implementation.

If you include it, make it operational. Mail sent to that address must be monitored or automatically processed, and it must result in a real opt-out. A dead mailbox is worse than no fallback because it makes an unsubscribe method appear functional when it is not.

Add the RFC 8058 one-click header

The RFC 8058 header has one standard value:

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

Use the spelling and capitalization shown above. Header field names are case-insensitive under email standards, but copying the conventional format reduces implementation mistakes and makes troubleshooting easier.

The full recommended pair is:

List-Unsubscribe: <https://email.example.com/unsubscribe/v1/4d1d34e0a0f84de3b8aa3c2f6a1d9e34>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Your HTTP endpoint should accept an HTTP POST request with form data containing this parameter:

List-Unsubscribe=One-Click

A typical request resembles this:

POST /unsubscribe/v1/4d1d34e0a0f84de3b8aa3c2f6a1d9e34 HTTP/1.1
Host: email.example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 26

List-Unsubscribe=One-Click

The endpoint should identify the recipient and subscription scope using the opaque token in the URL, not by trusting an arbitrary email address submitted in a POST body.

Return a successful HTTP response

When the request is valid and the opt-out has been applied, return a 2xx response. 204 No Content is a clean choice when the requester does not need a page body; 200 OK is also appropriate.

Examples:

HTTP/1.1 204 No Content

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

Unsubscribed

Do not return a redirect to a login page, a survey, or a confirmation form for the RFC 8058 POST action. That turns a one-click unsubscribe into a multi-step workflow.

If the token is expired, malformed, or unknown, use a response that does not reveal recipient information. A 404 Not Found or a generic 400 Bad Request can be reasonable, depending on your security model. Record enough internal detail to investigate failures, but do not expose email addresses or subscription data in the response.

Make the operation idempotent

An unsubscribe endpoint should be idempotent: repeating the same request should leave the recipient unsubscribed without causing an error.

That matters because network retries happen. A mailbox provider, proxy, or your own infrastructure may repeat a request after a timeout. If a recipient has already been unsubscribed, return a 2xx response rather than treating the second request as a failure.

A practical decision flow is:

Validate the URL token and its signature or database lookup.
Identify the recipient and the exact subscription category.
Set the category to unsubscribed if it is still active.
Store the event time, source, and message or campaign context where available.
Return 204 No Content or 200 OK whether the state changed now or was already unsubscribed.

Build a secure unsubscribe endpoint

The header is only as reliable as the endpoint behind it. A weak implementation can leak recipient information, allow token guessing, or unsubscribe someone from the wrong class of messages.

Scope the unsubscribe correctly

The token should map to a clear preference scope. For example, a person may want to stop a weekly product newsletter while continuing to receive account notices and receipts.

Common scopes include:

One campaign list, such as weekly-newsletter
One marketing channel, such as promotional email
All non-transactional marketing email
A preference-center record that preserves granular subscriptions

Do not let a one-click request disable essential transactional or security communications unless the recipient is closing the account or the communication is genuinely optional.

Use tokens that cannot be guessed

A sequential URL such as this is unsafe:

https://email.example.com/unsubscribe?user_id=1042

An attacker could increment the ID and potentially unsubscribe other people. Use a cryptographically random token or a signed token with enough entropy. Store only a hash of long-lived tokens where practical, just as you would handle password-reset tokens.

You can also expire tokens, but balance expiry against usability. An email may be opened months later. If an expired token prevents the header-based unsubscribe from working, provide a safe recovery path on the GET page, such as asking for an email address and sending a separate preference-management link. The RFC 8058 POST action itself should remain direct when the token is valid.

Keep GET and POST behavior separate

A strong pattern is:

GET /unsubscribe/<token> displays a human-facing confirmation or preference page.
POST /unsubscribe/<token> with List-Unsubscribe=One-Click applies the one-click opt-out immediately.

Do not make a GET request immediately unsubscribe someone. Security scanners and link-preview systems may follow GET links automatically. A GET page can explain the subscription and offer optional preference controls, while the explicit RFC 8058 POST path remains safe for mailbox-provider automation.

Avoid login gates and anti-bot challenges

The one-click POST endpoint should not require cookies, an account session, JavaScript, CAPTCHA, or a human browser. Mailbox providers make the request on the recipient’s behalf, so they will not have the recipient’s web session.

Rate limiting is still appropriate. Apply limits by IP, token pattern, or endpoint, but do not block legitimate mailbox-provider traffic merely because it comes from shared infrastructure. The endpoint should be lightweight and available; an unsubscribe failure is both a user-experience problem and a deliverability risk.

Add the headers through SMTP or an email API

Email headers are part of the message itself. Whether you send through an SMTP relay or a REST API, the final RFC 5322 message must contain the header pair before it is delivered.

SMTP example

With SMTP, add the headers to the message content before the blank line that separates headers from the body:

From: Example Updates <updates@example.com>
To: recipient@example.net
Subject: Your weekly product update
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
List-Unsubscribe: <https://email.example.com/unsubscribe/v1/4d1d34e0a0f84de3b8aa3c2f6a1d9e34>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

This is the message body.

If you construct raw MIME messages, do not add headers after the blank line. Anything after that separator is message body content, not an email header.

REST API considerations

REST email APIs commonly expose a custom-header field, a raw-message mode, or a message object that supports arbitrary headers. The field name and JSON shape differ by provider, so use the provider’s documented custom-header mechanism rather than copying an example intended for a different API.

If your platform supports both SMTP relay and REST delivery, the required message-level headers are the same. The transport changes, but the recipient receives a standards-formatted email with List-Unsubscribe and List-Unsubscribe-Post in the header block. Check your provider’s email API reference and setup guides to confirm how custom headers are passed through and whether any reserved headers are managed by the service.

Sign the headers with DKIM

RFC 8058 requires the List-Unsubscribe and List-Unsubscribe-Post fields to be covered by a valid DKIM signature. This protects against a third party adding or changing an unsubscribe target in transit.

If your sending service applies DKIM after accepting your message, verify that the delivered DKIM-Signature has an h= tag that includes both headers. A simplified example looks like this:

DKIM-Signature: v=1; a=rsa-sha256; d=example.com; s=mail2026;
 h=from:to:subject:list-unsubscribe:list-unsubscribe-post:mime-version:content-type;
 ...

Do not manually modify signed headers after DKIM signing. A post-signing change can invalidate the signature and undermine authentication.

Authentication and DNS records that support deliverability

List-Unsubscribe is not a DNS record. You do not publish it in SPF, DKIM, or DMARC. It is a per-message email header.

However, mailbox providers evaluate unsubscribe behavior alongside sender authentication and reputation. A well-built unsubscribe flow cannot compensate for missing authentication, and an authenticated domain can still develop a poor reputation if it makes opt-out difficult.

SPF example

SPF authorizes sending infrastructure for the SMTP envelope sender domain. A syntactically valid zone-file-style example is:

example.com. IN TXT "v=spf1 ip4:192.0.2.0/24 -all"

If you send through an email platform, that platform will provide the exact include: mechanism or IP authorization to use. Do not guess it and do not publish multiple SPF TXT records for one domain. Combine authorized sources into one record.

DKIM example

DKIM publishes a public key under a selector-specific hostname. The exact selector and key must come from your sender or signing system:

mail2026._domainkey.example.com. IN TXT "v=DKIM1; k=rsa; p=YOUR_FULL_PUBLIC_KEY"

The public key must be complete and unbroken in DNS. The p= value above is intentionally a placeholder; never copy it as a real record. Your delivered email’s DKIM-Signature header identifies the selector with s= and signing domain with d=.

DMARC example

DMARC is published at _dmarc and connects the visible From domain to aligned SPF or DKIM authentication. A monitoring policy can look like this:

_dmarc.example.com. IN TXT "v=DMARC1; p=none; rua=mailto:dmarc-reports@example.com"

For large-volume senders, mailbox-provider requirements commonly include SPF, DKIM, and DMARC. Google’s bulk-sender guidance applies when a sender exceeds 5,000 messages per day to Gmail accounts, while Yahoo also requires bulk senders to support easy unsubscribe and honor requests within two days. Authentication, visible sender identity, low complaint rates, and an operational unsubscribe process work together.

Use DNS inspection tools such as MXToolbox to check published SPF, DKIM, and DMARC records. Remember that a DNS record being present is not enough: the actual message must authenticate and align correctly.

Keep a visible unsubscribe link in the email body

A List-Unsubscribe header does not replace the unsubscribe link in the message body.

A recipient may use a mail client that does not show a native unsubscribe control. They may also want to change preferences rather than stop every category of mail. Include a clearly visible footer link that works without a login and leads to an unsubscribe or preference-management experience.

Example HTML footer:

<p style="font-size:12px;color:#666;">
  You are receiving this email because you subscribed to Example Updates.
  <a href="https://email.example.com/preferences/v1/4d1d34e0a0f84de3b8aa3c2f6a1d9e34">Manage preferences or unsubscribe</a>.
</p>

The body link may go to a preference center, but the recipient should be able to find a complete opt-out without hunting through multiple screens. Avoid forcing a survey before unsubscribing. Asking for feedback after the opt-out is complete is less risky than making feedback a condition of the opt-out.

The header POST endpoint and the body link can use different UX. The header action should be direct and machine-processable. The body link can present choices, explain categories, or offer a broader preference center.

Test the implementation before a campaign

Test the exact message that your production sender will deliver. A locally generated MIME sample can prove that your code creates headers, but it cannot prove that your email provider preserves them, DKIM signs them, or a receiving mailbox accepts the message as intended.

Inspect the delivered source

Send a campaign-like test message to accounts at more than one mailbox provider. Open the original message source or raw headers and look for:

List-Unsubscribe:
List-Unsubscribe-Post:
DKIM-Signature:
Authentication-Results:

Confirm all of the following:

The headers appear before the message body.
The HTTPS URL contains the correct recipient-specific token.
The List-Unsubscribe-Post value is exactly List-Unsubscribe=One-Click.
DKIM passes.
The DKIM signature covers both unsubscribe headers.
SPF and DMARC pass as expected.
The message still contains a visible body unsubscribe link.

Test the POST endpoint directly

Use curl with a non-production test token to simulate the RFC 8058 request:

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

A successful response should be in the 2xx range. Repeat the same request and verify that it remains successful without creating duplicate events or changing unrelated preferences.

Also test the GET version of the URL. It should not silently unsubscribe the recipient. It can render a confirmation or preference page, but automated GET requests must not alter subscription state.

Use deliverability testing tools carefully

Tools such as mail-tester.com can help inspect message headers and authentication on a test message. They are useful for spotting missing headers, malformed MIME, SPF failures, or DKIM failures.

They are not a substitute for testing your unsubscribe endpoint and preference database. You should also test with real mailbox accounts, inspect application logs, and confirm that an unsubscribe request prevents future sends from the relevant campaign audience.

Common List-Unsubscribe header mistakes

The following mistakes are responsible for most failed implementations:

Adding only a footer link. A visible link is necessary, but it does not create a standards-based list header or RFC 8058 POST flow.
Adding only mailto:. It may be acceptable in some environments, but it is not a dependable one-click POST implementation.
Using GET to unsubscribe. Automated URL fetches can create accidental opt-outs.
Omitting List-Unsubscribe-Post. The HTTPS URL alone is a List-Unsubscribe method, not an RFC 8058 one-click signal.
Sending a non-standard POST body. Support the form parameter List-Unsubscribe=One-Click.
Requiring account login or JavaScript. A mailbox provider cannot use the recipient’s browser session.
Using predictable recipient IDs. Sequential IDs can expose or alter other recipients’ preferences.
Unsubscribing from transactional messages. Promotional preferences and required operational communications should be modeled separately.
Adding headers after DKIM signing. The final signed message must contain the headers.
Failing to suppress future sends. A successful endpoint response is meaningless if your campaign audience is not updated before the next send.

Operational practices after launch

Treat unsubscribe events as production data, not just a compliance checkbox. Your system should record when the request happened, which endpoint or source generated it, the preference scope changed, and the campaign or message context when available.

Apply suppression as quickly as your sending architecture allows. If campaigns are queued ahead of time, make sure the send worker re-checks suppression status shortly before delivery. Otherwise, a recipient might unsubscribe and still receive messages that were prepared earlier in the queue.

Monitor:

POST requests and response-code distribution
Token validation failures
Time from unsubscribe request to suppression
Complaint rates by campaign and list source
Bounces and invalid addresses by acquisition channel
Authentication results for campaign traffic

An unusually high unsubscribe rate is not necessarily bad. It can mean the list is aging, frequency is too high, expectations were unclear at sign-up, or a campaign reached the wrong segment. A functioning unsubscribe path is healthier than frustrated recipients marking messages as spam.

FAQ

Do I need both List-Unsubscribe and List-Unsubscribe-Post?

For RFC 8058 one-click unsubscribe, yes. List-Unsubscribe supplies the HTTPS URL and List-Unsubscribe-Post: List-Unsubscribe=One-Click signals that the URL accepts the one-click POST action. The base List-Unsubscribe header can exist alone, but that is not the complete modern one-click implementation.

Should every transactional email have a List-Unsubscribe header?

No. Use it for marketing and subscribed mail that recipients can stop receiving. Do not add it by default to password resets, security alerts, receipts, invoices, and other essential operational messages.

Can the unsubscribe URL contain an email address?

It can, but it should not. Email addresses in URLs can leak through logs, analytics systems, referrer data, and support screenshots. Use an opaque or signed recipient-specific token instead.

What response should my one-click endpoint return?

Return a 2xx response after applying the opt-out. 204 No Content is a good minimal response, and 200 OK is also valid. Make the endpoint idempotent so repeated requests remain successful.

Does List-Unsubscribe guarantee an unsubscribe button in Gmail or Yahoo?

No. Mailbox providers decide whether and where to show recipient-facing controls. Correct headers, valid authentication, a working endpoint, low complaint rates, and good sender reputation give your mail the best chance of qualifying.

How to Include a List-Unsubscribe Header (RFC 8058)