List-Unsubscribe header (RFC 8058) for cold email senders

In February 2024, Gmail and Yahoo started enforcing one-click unsubscribe for any sender doing >5,000 emails per day to their users. Microsoft followed shortly after. If your cold email tool isn't adding the right SMTP headers, your inbox-placement rate will tank as soon as you cross that volume threshold.

This post is the short technical breakdown.

The two headers

There are two related but separate headers, both defined in RFC 8058:

List-Unsubscribe: <https://yourdomain.com/unsub?u=ABC123&t=XYZ>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

List-Unsubscribe is the URL the mail client (Gmail, Yahoo) hits when the user clicks the "Unsubscribe" link rendered next to your From address. Must be HTTPS.
List-Unsubscribe-Post declares "I support one-click, you can POST to this URL with no user interaction." This is what unlocks the inline button in Gmail's UI.

Both must be present. Just List-Unsubscribe (the older RFC 2369 form) is insufficient for the new enforcement.

What hitting the URL looks like

When a user clicks unsubscribe in Gmail, Google sends a POST request:

POST /unsub?u=ABC123&t=XYZ HTTP/1.1
Host: yourdomain.com
Content-Type: application/x-www-form-urlencoded

List-Unsubscribe=One-Click

Your endpoint must:

Return 200 OK within 30 seconds
Suppress that recipient on subsequent sends, Gmail expects the next email to actually not arrive
Tolerate either a GET (some legacy clients) or a POST

You should also sign the URL, usually with HMAC of (user_id, list_id, timestamp) keyed by a server-side secret, so an attacker can't unsubscribe arbitrary recipients by guessing IDs.

Body-link unsubscribe is still required

The header is in addition to a CAN-SPAM-compliant unsubscribe link in the email body. Don't remove the body link. Some clients (especially older corporate Outlook) only honor the body link. Belt and suspenders.

What we did

Bulk Email Boxer's outbound dispatcher generates the unsubscribe URL once at render time, stamps it on both the List-Unsubscribe and List-Unsubscribe-Post headers, AND embeds it in the body footer. We HMAC-sign the URL with a server-side secret, and the unsubscribe endpoint records suppression in Postgres before returning 200.

Before we shipped this, our test mailbox at Gmail saw a ~22% spam-folder rate. After: under 4%. That single change moves the needle more than SPF / DKIM / DMARC tightening combined for most senders.

TL;DR

Add both List-Unsubscribe and List-Unsubscribe-Post SMTP headers
HTTPS only, signed URL
Endpoint returns 200 within 30s and actually suppresses the recipient
Keep your body footer unsubscribe link too
Test by sending to a Gmail account and checking the message source for both headers

For the broader deliverability picture, see the cold email deliverability checklist.