One-click unsubscribe and the List-Unsubscribe header

One-click unsubscribe means your message carries two headers, List-Unsubscribe with an HTTPS address and List-Unsubscribe-Post: List-Unsubscribe=One-Click, so the recipient’s mail client can unsubscribe them with a single request. Google and Yahoo require it from bulk senders for marketing and subscribed messages, and a link in the body alone does not satisfy them. For cold email the cost of doing it is small and it gives unhappy recipients something other than the spam button.

The mechanism comes from two standards. RFC 2369 (July 1998) defines the List-Unsubscribe header. RFC 8058 (January 2017, Standards Track) defines how to signal one-click behaviour on top of it.

The two headers

A compliant message contains both headers, plus a visible unsubscribe link in the body.

From: Anna Example <anna@example.com>
To: lead@recipient.example
Subject: Question about your onboarding process
List-Unsubscribe: <https://unsub.example.com/u/7f3c9a1e2b4d>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

What each part does:

• List-Unsubscribe holds one or more addresses in angle brackets, separated by commas, in order of preference (RFC 2369). RFC 8058 requires that it contain one HTTPS URI.
• List-Unsubscribe-Post must contain exactly the key-value pair List-Unsubscribe=One-Click, with no variations (RFC 8058).
• Google’s own example for bulk senders uses the same two headers with an HTTPS URL and says the message should also include a clearly visible unsubscribe link in the body.

You can add a mailto: address as a second entry. RFC 2369 allows several addresses, and the client uses the first one it supports. Do not rely on it: Google says that mailto and URL links in the body do not meet its one-click requirement.

What must be true for the headers to count

RFC 8058 sets rules for the sender and for the endpoint. The ones that cause real-world failures:

1. Sign the headers with DKIM. The message needs a valid DKIM signature, and both List-Unsubscribe and List-Unsubscribe-Post must be covered by it, listed in the h= tag of the signature. A message where the headers are added after signing, or left out of h=, fails this rule.
2. Use HTTPS. The URI must be HTTPS.
3. Accept a bare POST. The mail client sends a POST request with the body List-Unsubscribe=One-Click (content type application/x-www-form-urlencoded in the RFC’s example). The request must not include cookies, HTTP authorisation or other context. The unsubscribe URI therefore has to identify the recipient and message by itself, for example with an opaque token in the path.
4. Do not redirect. The RFC says the sender must not return an HTTPS redirect for the POST.
5. Act at once. The POST means “unsubscribe this person”. Do not show a confirmation form as the only way to complete it; that is what the visible body link is for.

The RFC also says a mail receiver must not perform the POST without user consent. That is a rule for mail clients, and it is why the endpoint can safely treat any POST as a real request.

An illustrative signature header, with the two list headers covered:

DKIM-Signature: v=1; a=rsa-sha256; d=example.com; s=s1;
  h=from:to:subject:date:message-id:list-unsubscribe:list-unsubscribe-post;
  bh=...; b=...

What an endpoint looks like

POST /u/7f3c9a1e2b4d HTTP/1.1
Host: unsub.example.com
Content-Type: application/x-www-form-urlencoded

List-Unsubscribe=One-Click

A good response is a plain 200 OK. Behind it, the handler should:

• Look up the recipient from the token, not from a session.
• Mark the address as unsubscribed for the whole workspace, not only for the one campaign.
• Be safe to call twice; mail clients may retry.
• Return the same answer for an unknown token as for a known one, so the endpoint does not reveal who is on your list.

These are engineering choices, not statements from the RFC, except for the points about cookies and redirects above.

What Google, Yahoo and Microsoft say

Yahoo and Google define bulk differently. Google counts around 5,000 messages a day to Gmail; Yahoo says it does not specify a threshold. If you send from many mailboxes, do not use the thresholds as a reason to skip the header.

Why it matters more for cold email than for newsletters

A subscriber who no longer wants a newsletter chose to receive it once, and usually knows where the unsubscribe link is. A cold recipient never chose anything. If they cannot leave quickly, the remaining options are to ignore the message or to report it as spam, and Google and Yahoo both measure the spam report. One-click unsubscribe lets mail clients that support it offer an unsubscribe control of their own, so leaving can cost one action instead of a hunt through the message.

Treat three kinds of opt-out the same way:

1. The header POST from the mail client.
2. A click on the unsubscribe link in the body.
3. A written reply such as “remove me” or “stop”. These are real opt-outs and should end all outreach to that person, on every channel.

A spam complaint is the fourth kind. You do not choose to honour it; the address must not receive anything more from you.

Common mistakes

• Body link only. Both Google and Yahoo say this does not satisfy the requirement.
• mailto: only. Google says mailto does not meet it.
• Headers not signed. Without DKIM coverage of both headers, receivers can ignore them.
• A redirect or a login wall on the endpoint. The POST carries no cookies or authorisation, and redirects are forbidden.
• Campaign-level unsubscribe. Someone who unsubscribed from step 1 and gets step 3 from another campaign will complain. Unsubscribe from the workspace.
• Slow processing. Yahoo’s limit is 2 days. A delay after a complaint is the worst case.
• Hiding the link. Google requires it to be clearly visible. A grey, one-pixel link brings spam reports instead of unsubscribes.

Testing

1. Send a campaign message to a Gmail address you control and open the original message. Check that both headers appear exactly as above.
2. In the same view confirm dkim=pass, and check that h= in the signature includes both header names.
3. Run the POST yourself with curl -i -X POST -d "List-Unsubscribe=One-Click" https://unsub.example.com/u/<token> and confirm a 200 response with no redirect.
4. Confirm the address now appears in your suppression list and is excluded from the next send, on every channel you use.

How Dooxout handles this

Campaign email from Dooxout carries the List-Unsubscribe and List-Unsubscribe-Post headers, and there is an unsubscribe page for recipients who prefer a link. An unsubscribe or a spam complaint puts the address on the workspace suppression list, and that list applies on email, LinkedIn, WhatsApp and Telegram alike. It is the one rule in the platform that cannot be turned off, by a user or by the agent. The MCP server exposes an action to add an address to the suppression list and no action to remove one.

Everything else in Dooxout is a limit you set or a recommendation you can accept or decline. Suppression is not. See guardrails and security and MCP quickstart.