One-click unsubscribe: how List-Unsubscribe works and how to add it

The two headers

List-Unsubscribe: <https://example.com/unsubscribe/abc123>, <mailto:unsubscribe@example.com?subject=unsubscribe>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

• List-Unsubscribe gives one or more places to send the request: an https address, a mailto address, or both.
• List-Unsubscribe-Post tells the mail app it may do a one-click unsubscribe: send a POST to the https address, with no page to confirm. This is the standard in RFC 8058.

What your endpoint must do

1. Accept a POST with the body List-Unsubscribe=One-Click, with no sign-in and no confirmation page.
2. Know who it is for from the address alone. Put a signed token for the recipient in the link, because the request carries nothing else.
3. Remove them promptly. Gmail and Yahoo expect a request to be honored within two days. Faster is better, and there is no reason not to do it at once.
4. Answer with a success status (a 200 is fine). Do not redirect.
5. Also work on a GET by showing a page, for people who paste the link into a browser.

The rules that catch people out

• The headers need to be covered by your DKIM signature. Most sending services do this for you.
• The https address must be a real https address. Plain http is not accepted.
• Never put the one-click header on a message you do not send in bulk, such as a password reset. Those do not need it, and an unsubscribe button on a security email is confusing.
• An unsubscribe must apply to the kind of mail it is on. If someone leaves your newsletter, do not keep sending them the newsletter under a different name.

With SendSend

Broadcasts sent to your audiences include these headers for you, with a unique link for each contact, and the unsubscribe is recorded and enforced. If you send bulk email yourself through the API, add the headers when you send:

curl -X POST https://api.sendsend.email/v1/emails \
  -H "Authorization: Bearer $SENDSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "News <news@mail.example.com>",
    "to": ["maria@example.org"],
    "subject": "This month",
    "html": "<p>Hello</p>",
    "headers": {
      "List-Unsubscribe": "<https://example.com/u/abc123>",
      "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
    }
  }'

SendSend checks the header, and refuses one that is not valid, such as an http address or a one-click header with no List-Unsubscribe beside it. See the broadcasts guide and the Gmail and Yahoo requirements.

How to test it

1. Send yourself a message at a Gmail address and open it. In the header area you should see “Unsubscribe” next to the sender.
2. Press it, and check your server received a POST and that the address was removed.
3. Send again and confirm you do not get it.