List-Unsubscribe header builder for one-click unsubscribe

One-click unsubscribe takes two headers: List-Unsubscribe with an https URL, and List-Unsubscribe-Post set to List-Unsubscribe=One-Click. Gmail and Yahoo require both on marketing mail from bulk senders. Build them below or paste your own to check them.

Headers to add

Fill in the fields above.
  • Fix: Enter an https unsubscribe URL, a mailto address, or both.

Everything you type stays in this browser. Nothing is sent anywhere.

How to use it

  1. Enter the https URL that unsubscribes one recipient. Put a per-recipient token in the path so the endpoint knows who is leaving.
  2. Add a mailto address if you also want to support clients that only read mailto. It is optional.
  3. Leave the one-click box ticked to include List-Unsubscribe-Post.
  4. Copy the headers, or the JSON object if your email API takes a headers map.
  5. Add the headers to every marketing message, and include both in your DKIM h= list.
  6. Run the curl test against your endpoint. It should unsubscribe the recipient and return a 2xx status.

What the endpoint must do

When a recipient clicks the unsubscribe button in Gmail or Yahoo, the mailbox provider sends an HTTP POST to your URL with the body List-Unsubscribe=One-Click. The request carries no cookies and no login, so the token in the URL is the only way to identify the subscriber.

Unsubscribe on that POST and return a 2xx response. A GET to the same URL should show a confirmation page and change nothing, because link scanners fetch URLs in messages and would otherwise unsubscribe everyone.

Questions

What is the List-Unsubscribe-Post header?

It tells the mailbox provider that your https URL accepts a one-click POST. Its value must be exactly List-Unsubscribe=One-Click, as defined in RFC 8058.

Can I use only a mailto link?

A mailto works as a fallback, but one-click needs an https URL. Gmail and Yahoo expect an https URL with List-Unsubscribe-Post from bulk senders, so include one.

Do I need to sign the headers with DKIM?

Yes. RFC 8058 requires the message to carry a valid DKIM signature that covers List-Unsubscribe and List-Unsubscribe-Post, so a forwarder cannot tamper with them.

Should the URL contain the email address?

Use an opaque token instead. A raw address in the URL leaks the recipient and lets anyone guess other unsubscribe links.

How fast must I honor an unsubscribe?

Google asks senders to complete unsubscribe requests within 48 hours, and Yahoo within two days. Removing the address as soon as the POST arrives meets both.

Do transactional emails need these headers?

No. Google requires one-click only for marketing and promotional messages. Receipts, password resets and other account messages are exempt.

See also

More free email tools

Updated .

As seen on

Fazier badgeFazier badgeRelayMail, featured on Smol LaunchRelayMail, featured on Smol LaunchLaunched on StartupBaseLaunched on StartupBaseOpenHunts Club MemberFeatured on Aura++Featured on Aura++Featured on Twelve ToolsFeatured on Twelve Tools