# One-click unsubscribe One-click unsubscribe is a pair of headers that let a mail client show its own unsubscribe control and act on it with a single POST — no landing page, no login, no confirmation step. The largest mailbox providers require it of bulk senders. Connect enforces the honouring side; adding the header to a message is the sending mailbox's business, not something these sources document Connect doing. - **Status:** Reference - **Audience:** both - **Channels:** email - **Last verified:** 2026-09-10 - **Canonical:** https://connectbyjbrh.com/docs/technology/unsubscribe/ ## The two headers ```http List-Unsubscribe: , List-Unsubscribe-Post: List-Unsubscribe=One-Click ``` `List-Unsubscribe` is the older of the two and may carry a `mailto:` URI, an `https:` URI, or both. On its own it is a hint: the client may show a control, and following the link lands the person on a page where something further is expected of them. `List-Unsubscribe-Post` is what makes it one click. Its presence tells the client it may send `POST` with the body `List-Unsubscribe=One-Click` to the https URI, and that doing so is sufficient. The client does this itself, from its own infrastructure, without the person's browser being involved at all. > **Careful** Because the client acts without a browser session, the endpoint must identify the recipient entirely from the opaque token in the URI, must not require a login, must not present a preference page, and must not act on `GET`. Security scanners and link prefetchers follow links; a `GET`-triggered unsubscribe silently opts people out who never touched the message. ## What the obligation actually is Three separate pressures point at the same behaviour, and it helps to keep them apart because they apply to different senders. **Mailbox provider rules** — The largest consumer providers publish bulk-sender requirements that include offering one-click unsubscribe and acting on a request within a short window measured in days. These are conditions of delivery, enforced by filtering rather than by law. **Marketing law where the recipient is** — Regimes differ: some require a working opt-out mechanism in every commercial message and a deadline for honouring it; others require consent before the first message and an easy withdrawal after. Which applies depends on where the recipients are, not where the sender is. **The reputational one** — A person who cannot find the unsubscribe control uses the spam button instead, which costs far more than the opt-out would have. The third is the one that decides design arguments. Making an unsubscribe slightly harder never retains a reader; it converts an opt-out into a [complaint](/docs/technology/feedback-loop/). ## Where implementations go wrong 1. The token is scoped to a campaign, so unsubscribing from one message leaves the person subscribed to everything else the business sends. 2. The endpoint returns a redirect to a preference centre. A one-click POST expects to be finished; anything else means the request may not be honoured. 3. The header is added to transactional mail, so a receipt offers to stop receipts — and someone takes it up, then does not receive the next invoice. 4. Opt-outs are recorded in the sending tool rather than in the business's own [suppression list](/docs/technology/suppression/), so changing supplier loses every one of them. 5. The `mailto:` form is offered and nobody monitors the mailbox it points at. ## Does Connect use one-click unsubscribe? Connect enforces the receiving half. Unsubscribe status sits alongside suppression, complaints and do-not-contact in the single compliance check that runs before any outreach leaves, so an address that has opted out is not contacted again by any outreach path. The sending half — whether a particular outbound message carries `List-Unsubscribe` and `List-Unsubscribe-Post` — is a property of the message and the mailbox it goes through. Connect sends via the workspace's own Gmail, Microsoft Graph or IMAP/SMTP mailbox, and the sources behind this page do not document Connect composing those headers, so the page does not claim it. If you run bulk campaigns from a domain that also carries Connect's conversational mail, the headers are the campaign platform's responsibility. The practical rule for a Connect workspace: if an unsubscribe reaches you anywhere — a header POST at your campaign tool, a reply saying stop, a phone call — record it as a suppression here, because that is the record the outreach gate reads. ## Questions ### Does a one-click unsubscribe need a confirmation page? No, and adding one breaks it. The client posts without a browser and expects the request to be complete; a confirmation step means the opt-out is not recorded until a human does something else, which is exactly what the mechanism was designed to remove. ### Should transactional messages carry the header? Generally not, because there is nothing to unsubscribe from — an invoice is not a subscription. The exception is a message that is arguably both, and the honest fix there is to split it rather than to offer an opt-out from something the recipient needs. ### Someone replied 'stop' instead of using the link. Does that count? Treat it as an opt-out. The mechanism exists for the sender's convenience, not as a required form of words, and a business that only honours the button will eventually explain that distinction to somebody who is not interested in it. Record it as a suppression so every later path sees it. ## Related - [Suppression lists](https://connectbyjbrh.com/docs/technology/suppression/) - [Transactional and marketing email](https://connectbyjbrh.com/docs/technology/transactional-vs-marketing/) - [Complaint feedback loops](https://connectbyjbrh.com/docs/technology/feedback-loop/) - [STOP and opt-out keywords](https://connectbyjbrh.com/docs/technology/stop-keyword/) - [Email in Connect](https://connectbyjbrh.com/docs/email/) ## What this page is based on - RFC 8058 — Signalling One-Click Functionality for List Email Headers (https://www.rfc-editor.org/rfc/rfc8058) - RFC 2369 — The Use of URLs as Meta-Syntax for Core Mail List Commands (https://www.rfc-editor.org/rfc/rfc2369) - Source pack: email — `docs-source/sources/CHANNELS.md` §1 (one compliance check before outreach) - Connect capability registry (`docs-source/facts.py`)