List-Unsubscribe Header and One-Click Unsubscribe Setup

The List-Unsubscribe header lets a mailbox provider show its own unsubscribe control for your email, and the List-Unsubscribe-Post header lets that control finish the job with a single HTTPS request. Neither replaces the visible unsubscribe link in the message body; they work alongside it. It is useful for newsletter owners, bloggers and store owners who send email campaigns. This article is not legal advice; for questions about consent or obligations, consult the relevant rules and a qualified professional.

Body link, header and Gmail's request

An email has two unsubscribe routes, and each one serves a different reader. The link in the body is for the person reading the message. The header field is for the mail program or mailbox provider that processes it, which can offer an unsubscribe option in its own interface. Both should lead to the same outcome, and neither can stand in for the other.

The body link

Gmail's email sender guidelines (Opens in a new tab) say that marketing and subscribed messages must support one-click unsubscribe and include a clearly visible unsubscribe link in the message body. The guidelines therefore do not treat the header as enough; the visible link is part of the requirement.

The header field

The header gives the receiving system a way to unsubscribe the user before the message is even read. RFC 2369 (Opens in a new tab) describes the List-Unsubscribe field as the command to directly unsubscribe the user, removing them from the list, and says the command is preferably a mail command. The RFC also says these fields must only be generated by mailing lists and not by end users, and a message may carry at most one of each field. Writing two List-Unsubscribe fields in one message is therefore a mistake; several options belong inside a single field.

What Gmail asks for

To set up one-click unsubscribe for Gmail messages, the guidelines say to include both headers in outgoing messages. The examples on the page show the post header with the value List-Unsubscribe=One-Click and the unsubscribe header holding an HTTPS address inside angle brackets. The page ties the requirements to February 1, 2024. The wording of the bulk-sender threshold differs slightly between the page's heading and its body, so check the current page to see whether your volume puts you in scope.

Header syntax: addresses and confirmation

The value of the List-Unsubscribe field is made of one or more addresses, each enclosed in angle brackets. Under RFC 2369, mail transfer agents must not add whitespace inside the brackets, and clients should ignore a field that does not begin with an opening angle bracket. A formatting slip can therefore silence the whole header.

Several addresses in one field

RFC 2369 allows a list of alternate addresses separated by commas, each in angle brackets. The addresses have an order of preference from left to right. Clients should use the leftmost address whose protocol they support, use only one address per command, and try another only if the first one fails. If you list two addresses, put the one you prefer on the left.

Why mailto still appears

RFC 2369 says a mailto command should normally be included to support users who have no access to non-mail protocols. Its example pairs an HTTP address with a mailto address so web-capable clients can use the web option. RFC 8058 requires one HTTPS address for the one-click mechanism and allows other addresses, such as mailto, to appear as well.

User confirmation

The security section of RFC 2369 requires that the user have a chance to confirm any action before it is executed. For mailto commands, a client can prepare the message without sending it so the user can review it. The same principle returns in RFC 8058: the mail receiver must not perform a POST without user consent.

One-click POST, header by header

RFC 8058 (Opens in a new tab) defines one-click functionality driven by header fields. The background is that anti-spam software often fetches the URLs it finds in headers automatically. If a plain GET request could finish an unsubscribe, a scanner could cancel a subscription by accident, so one-click is defined over POST.

Two headers and one key

Under sections 3.1 and 5, the sender includes one List-Unsubscribe header and one List-Unsubscribe-Post header. The post header must contain the single key and value pair List-Unsubscribe=One-Click. Section 6 explains that limiting it to this one pair prevents an attacker from simulating arbitrary form submissions. The List-Unsubscribe header must contain one HTTPS address, and other addresses such as mailto may also appear.

The signature requirement

Section 4 states that senders must apply at least one valid DKIM signature, and that the List-Unsubscribe and List-Unsubscribe-Post headers must be covered by the signature and listed in its h= tag. If a message lacks the required signature, the receiver should not offer one-click unsubscribe for it. Setting up header signing is part of the sender configuration, not an optional extra.

The request itself

The receiver sends an HTTPS POST to the address in List-Unsubscribe. Per section 3.2, the body carries the key and value pair from the post header. The content type should be multipart/form-data and may be application/x-www-form-urlencoded. The POST target is the same address used for a manual GET unsubscription, so one handler on your server can serve both.

Redirects, cookies and the token

No redirects, no cookies

Section 3.1 says the sender must not return an HTTPS redirect, because redirected POST requests have often been converted to GET. It also says the POST request must not include cookies, HTTP authorization or any other context information. Section 6 explains the reason: the server cannot link the request to earlier web activity. Your unsubscribe address therefore cannot depend on a logged-in session or a cookie. It has to identify the subscriber from the address itself.

The opaque token

The RFC says the address should include an opaque or hard-to-forge component, and the server should verify it. The security section notes that anyone with access to a message can trigger the recipient's unsubscription, which is typical of existing List-Unsubscribe use. It adds that an unsubscribe request can reveal that an address is valid. Practical suggestion: carry an unguessable token in the address instead of a plain email address or a sequential number, and avoid putting anything in the response that confirms or denies an address.

Which format to write

Decision rule: which pieces should I implement?

1. If you send to Gmail addresses and are unsure whether the guidelines apply, add the visible link, the HTTPS address and the post header, and include both in the signature.
2. If your sending tool adds the headers, do not add them by hand; verify that one-click is enabled and signed.
3. If you send with your own code, build the HTTPS endpoint, the token and the DKIM signing before you add the headers.
4. If you want a mailto fallback, place it to the right of the HTTPS address so the preference order favors HTTPS.
5. Before shipping, test that the address needs no redirect and no session.

Hosted service or your own server

How much of this you build yourself depends on how you send. The rules stay the same; the person responsible changes.

If a newsletter service sends your mail

Depending on the service, header generation, the hosting of the unsubscribe address and the closing of the record may be handled for you. Your tasks are then to find the one-click setting, confirm that the service signs with your own domain, and inspect the raw headers of a test message. If the service documentation does not mention one-click unsubscribe, do not assume it; ask the support team in writing. The RFCs and Gmail's guidelines say nothing about any particular service.

If you send from your own server

If you send from your own server, you write the endpoint. Practical suggestion: look up the subscriber from the token in the address and return an error for an invalid token. On a valid POST, close the subscription and return a success response. If the same token arrives again, return success rather than an error, since the receiving system may repeat a request and the record is already closed. Do not show the subscriber's address in the response. Do not redirect, and do not wait for a cookie. Apart from the redirect and cookie rules, these behaviors are suggestions drawn from general practice, not RFC requirements.

Keeping the body link and endpoint consistent

Gmail's guidelines ask for both the one-click headers and a clearly visible link in the body. Consistency means a reader reaches the same result no matter which route they take.

One handler, one record

The header address and the body link should close the same subscription record in the same way. Because RFC 8058 says the POST target is the same address used for a manual GET, a single handler suffices on the server. Two separate flows invite inconsistencies, such as one that records the opt-out and another that forgets it.

What happens on a GET

RFC 8058 defines the one-click behavior only for POST and does not say how a GET to that address should be handled. Section 1 notes that anti-spam software often fetches URLs found in headers. Practical suggestion: when a GET reaches the body link, show a short confirmation page instead of finishing the unsubscribe at once, so an automated fetch cannot cancel a subscription. This is a suggestion; the RFC sets no rule for GET.

Testing, monitoring and an example

Writing the headers is not enough. They must arrive at the recipient intact. A sending provider may rewrite, reorder or leave out headers when it signs, so test the message as it arrives, not as you composed it.

Example scenario: a regional recipe-box subscription

Example scenario: a small recipe-box subscription business sends a weekly offers email through a campaign tool and enables one-click unsubscribe. On a test message sent to a personal mailbox, the raw headers show the List-Unsubscribe field with an HTTPS address, but no List-Unsubscribe-Post field. The owner finds that the tool turns the post header on with a separate setting, switches it on and sends again. Now both fields are present, but the h= list of the DKIM signature does not include the post header. The owner asks the sending provider to extend the list of signed headers. In the next test, both headers are signed, and the owner confirms that a POST without cookies closes the record.

Test checklist

• The message carries exactly one List-Unsubscribe and one List-Unsubscribe-Post field.
• The post header value is exactly List-Unsubscribe=One-Click.
• The List-Unsubscribe field holds an HTTPS address in correct angle brackets.
• Both headers appear in the h= tag of the DKIM signature.
• The address does not redirect.
• A cookieless POST closes the subscription record.
• The visible body link closes the same record.
• No campaign email reaches the address after unsubscribing.

What to monitor

Unsubscribe handling is not a set-and-forget task. Repeat the header test whenever you change the sending provider, the newsletter tool or the message template. Check the server logs for failed responses (4xx and 5xx) on the unsubscribe address: a failed POST can leave a recipient believing they have unsubscribed while the record stays open, which means unwanted email and damage to your sender reputation.

How to collect and record consent is a separate subject, covered in the article on email consent and privacy-compliant newsletter subscriptions.

Records, counts and other recipients

If you send partner or sponsor emails from your own list, their opt-out route must connect to your list. For how to disclose paid content, see sponsored content disclosure. If your media kit lists a contact address, make sure that a reply asking to be removed is handled too.

Counting opt-outs

Counting unsubscribes tells you something about the health of a newsletter. Seeing which campaign was followed by a rise in opt-outs can guide decisions about content and frequency. If you tag links for analysis, the logic in UTM, GA4 and Search Console reporting is a starting point. Keep in mind that the one-click address must not redirect under RFC 8058, so use a query parameter for a label and never a redirect.

Recipients other than Gmail

Gmail's own guidelines and the RFCs do not describe how other mailbox providers display these headers or when they offer a one-click control; check each provider's current documentation. Since RFC 8058 expects a valid DKIM signature before a receiver offers one-click for a message, a correct signature is a common prerequisite either way.

Keep the exit short

A reader who clicks the visible link should be able to finish with one action on a short confirmation page. A long survey, a login wall or a multi-step form defeats that. If you want feedback, offer an optional question after the opt-out is complete. This is a suggestion; Gmail's guidelines do not discuss surveys, but their aim is to make leaving simple.

Mistakes by layer

Each of these follows from a rule or warning in RFC 8058 or Gmail's guidelines. None is a guarantee about outcomes, but each can make the mailbox control disappear or fail.

Header mistakes

• Two List-Unsubscribe fields in one message, when RFC 2369 allows at most one.
• Addresses outside angle brackets, or whitespace inside them.
• Extra keys in the post header value.
• A plain HTTP address for one-click, when RFC 8058 requires HTTPS.
• Leaving the headers out of the DKIM signature.

Endpoint mistakes

• A redirect from the unsubscribe address, which RFC 8058 forbids.
• Expecting a cookie or authorization in the POST.
• A guessable number or plain email address in the URL with no server-side check.
• Allowing opt-out by GET only, when one-click needs POST.

Process mistakes

• Switching sending providers without re-testing the headers.
• Dropping the visible body link and relying on the header alone, when Gmail's guidelines ask for both.
• Keeping opt-outs in a separate list that the main sending flow never reads.

Setup order and glossary

The parts are easy to understand one by one. The harder task is putting them in order, and the sequence below lets you start each step only after the previous one is confirmed.

Six steps

1. Confirm that DKIM signing works for your domain; header signing depends on it.
2. Build the unsubscribe endpoint: HTTPS, no redirect, no cookie, with a token.
3. Call it by hand twice with the same token and confirm both calls succeed.
4. Add the HTTPS address to List-Unsubscribe, optionally a mailto address to its right, and add List-Unsubscribe-Post with exactly List-Unsubscribe=One-Click.
5. Add both headers to the list of signed headers.
6. Send a test message and inspect the raw headers, the signature list and the mailbox interface.

Quick glossary

The first three rows follow RFC 8058 and Gmail's guidelines; the last two are practical terms. Keeping the difference in mind helps you separate what is required from what is advised.

Frequently Asked Questions

What is the List-Unsubscribe header?

It is a header field that tells the receiving system how a subscription can be ended, using one or more addresses in angle brackets, such as mailto or HTTP(S) addresses separated by commas. Under RFC 2369, a message may carry at most one such field, and the addresses are preferred from left to right.

What does List-Unsubscribe-Post do?

It tells the receiving system to send a single HTTPS POST to the unsubscribe address. Its value must be exactly List-Unsubscribe=One-Click. RFC 8058 also requires an HTTPS address in List-Unsubscribe and requires both headers to be covered by a DKIM signature.

Can I drop the visible unsubscribe link and rely on the header?

Gmail's sender guidelines ask for one-click unsubscribe headers and also a clearly visible unsubscribe link in the message body. The header does not replace the link. Both should close the same subscription record.

Can the unsubscribe address redirect?

No. RFC 8058, section 3.1, says the sender must not return an HTTPS redirect, because redirected POST requests have often been converted to GET. The address should answer the POST directly, without cookies or authorization.

Is there a legal duty tied to this header?

That question calls for a legal assessment, and this is not legal advice. The header fields and Gmail's guidelines are technical definitions. For consent and opt-out obligations, consult the relevant rules and a qualified professional; sender guidelines are a platform rule and do not replace a legal provision.

How do I check that the headers work?

Send a test message and inspect the raw headers as they arrive. Confirm one List-Unsubscribe field and one List-Unsubscribe-Post field, an HTTPS address, and both headers in the DKIM h= list. Then call the address with a cookieless POST and check that the visible link closes the same record.

Conclusion

A correct setup rests on three points: header syntax that follows RFC 2369 and RFC 8058, an HTTPS endpoint that works without redirects or cookies, and a visible body link that closes the same record. Adding the headers is not enough; test the message as it arrives and confirm that the DKIM signature covers both. Sender guidelines can change, so check the current Gmail page before you rely on a threshold or date. This article is not legal advice.

If you want your newsletter and content in front of a wider audience, you can browse guest post listings at Akua Adforce; scope and terms are on the product page.