List-Unsubscribe and one-click headers

In February 2024 Google and Yahoo announced bulk-sender requirements that included mandatory one-click unsubscribe support. Two years later, getting these headers wrong is a guaranteed deliverability hit.

The headers

A correct pair looks like this:

List-Unsubscribe: <mailto:[email protected]?subject=unsub>, <https://example.com/u/{token}>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Note what's there:

• Two values in List-Unsubscribe: a mailto AND an HTTPS URL.
• The URL contains an unguessable token specific to the recipient.
• List-Unsubscribe-Post is exactly the literal string List-Unsubscribe=One-Click.

What the receiver does

When a Gmail or Yahoo user clicks the unsubscribe link in the message header (not in the body — the one rendered above the message), the mail provider POSTs to your HTTPS URL with the body List-Unsubscribe=One-Click. Your endpoint must:

• Accept the POST without authentication.
• Process the unsubscribe immediately (the user is told it's done).
• Return a 2xx status.
• Not require a confirmation page or login.

If you fail this, the user can still mark the message as spam — and that complaint hits your reputation harder than the unsubscribe ever would.

Common mistakes

• Mailto-only. Pre-2024 this was acceptable; now it's a hard fail for bulk senders.
• Authentication required on the POST. The receiver isn't going to log in.
• Confirmation page. The user already confirmed by clicking. Adding another step makes them mark as spam instead.
• Token in the path AND a session cookie required. Same problem as above.
• HTTP instead of HTTPS. Receivers will refuse to POST to an HTTP URL.

What "bulk sender" means

Google defines bulk as 5,000+ messages per day to Gmail addresses. Yahoo's threshold is similar. If you're under that, you can technically skip these headers — but every modern ESP includes them by default and you should too.

If you only do one thing

Send a test through WillItInbox and look for the List-Unsubscribe checks. If they're warning or failing, fix them today. This is the lowest-effort, highest-impact compliance fix in modern email.