Agent Wranglers

EML-27Required

Offer one-click unsubscribe

Add List-Unsubscribe and List-Unsubscribe-Post headers to every marketing or list message, so mail apps can unsubscribe in one click.

By Agent Wranglers. Updated .

How to do it

Gmail and Yahoo delay or reject marketing mail without them from a bulk sender, as Meet the bulk sender rules sets out. Put exactly one HTTPS link in List-Unsubscribe (RFC 2369), optionally next to a mailto: address. Add List-Unsubscribe-Post: List-Unsubscribe=One-Click (RFC 8058). Put an opaque token in the link that names the recipient and the list. A POST to the link unsubscribes at once, with no cookies, login or redirect. A GET shows a page with a button, because mail scanners follow links on their own. List both headers in the h= tag of your DKIM signature. Act on each request as Unsubscribe within two days says.

Examples

Plain text example

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

JavaScript example

app.get('/unsubscribe', (req, res) => res.send(confirmPage(req.query.t)));
app.post('/unsubscribe', express.urlencoded({ extended: false }), async (req, res) => {
  await suppressByToken(req.query.t);
  res.status(200).send('You are unsubscribed.');
});

Python example

@app.get("/unsubscribe")
def unsubscribe_page():
    return confirm_page(request.args["t"])

@app.post("/unsubscribe")
def unsubscribe():
    suppress_by_token(request.args["t"])
    return "You are unsubscribed.", 200

How to check

Send curl -X POST -d 'List-Unsubscribe=One-Click' to the link from a test message. It answers 200 without a redirect, and the next send skips the address. A plain GET leaves the address subscribed. The DKIM-Signature header's h= lists List-Unsubscribe and List-Unsubscribe-Post.

Sources

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/email/unsubscribe/one-click-unsubscribe">Agent Wranglers email playbook</a>. In code you write, add a comment next to it with the same link.