## Why the Unsubscribe Button Became a Deliverability Feature For years, the unsubscribe link was treated as a legal footnote. It sat in tiny gray text at the bottom of the email, sometimes led to a login page, and occasionally asked people to type their address before anything happened. Senders tolerated the friction because a hard-to-find unsubscribe seemed to keep the list bigger. That logic no longer holds.
When people cannot leave a list easily, they do the next easiest thing: they click "Report spam." A complaint does far more damage than an unsubscribe. It tells the mailbox provider that the message was unwanted, it feeds the sender's reputation scores, and enough of them push future mail toward the spam folder for everyone on the list, including the subscribers who actually want it.
Mailbox providers understood this long before many senders did, and they built a better exit directly into the inbox: a native **Unsubscribe** option shown next to the sender's name, powered by email headers rather than by a link in the body. In 2024 Gmail and Yahoo made support for the one-click version of that mechanism a requirement for bulk senders of marketing mail.
This guide explains how one-click unsubscribe works, the headers behind it, what the RFC 8058 standard requires, what the large mailbox providers expect, how to build the endpoint so it is fast and safe, and how to test it before your next campaign. It closes with a pre-send checklist and a short FAQ. ## Two Ways to Unsubscribe: The Body Link and the Header Every marketing email should give recipients two unsubscribe paths.
They serve different purposes, and you need both. ### The unsubscribe link in the body This is the familiar link in the footer of the email. It is visible to the reader, it can lead to a confirmation page or a preference center, and it is what most privacy and anti-spam laws have in mind when they require a clear way to opt out.
Mailbox providers also expect it: a header alone is not a substitute for a visible link in the message. ### The List-Unsubscribe header The header is invisible to the reader but visible to the mail client. It tells the mailbox provider where to send an unsubscribe request on the subscriber's behalf.
When a provider trusts the header, it can display its own unsubscribe control in the interface, usually at the top of the message near the sender name, sometimes also in a prompt when someone tries to report the message as spam. The value of the header is consistency. The subscriber does not have to scroll to the footer, interpret your design, or land on an unfamiliar page.
They press a button in an interface they already trust, and the client handles the rest. ## The Headers Behind One-Click Unsubscribe Two headers work together. The first has existed for a long time; the second is what makes the process truly one-click. ### List-Unsubscribe (RFC 2369) The `List-Unsubscribe` header was defined in RFC 2369 back in 1998, originally for mailing lists.
It contains one or more URIs enclosed in angle brackets and separated by commas. The two common forms are a `mailto:` address and an `https:` URL: ``` List-Unsubscribe: , ``` With only this header, a mail client that offers an unsubscribe button has two choices. It can send an email to the `mailto:` address, or it can open the `https:` URL in a browser.
Opening a URL is not really one click: the user lands on a page and may still need to confirm. And because a simple GET request to a URL is something that link scanners and preview tools also perform, a sender cannot safely unsubscribe anyone just because the URL was fetched.
### List-Unsubscribe-Post (RFC 8058) RFC 8058, published in 2017, solved that problem by adding a second header: ``` List-Unsubscribe: List-Unsubscribe-Post: List-Unsubscribe=One-Click ``` The second header signals that the HTTPS URL in `List-Unsubscribe` accepts a POST request that performs the unsubscribe immediately. When the subscriber presses the button, the mailbox provider sends an HTTPS POST to that URL with the body `List-Unsubscribe=One-Click`. No browser page opens, and no further action is needed from the subscriber.
The distinction between GET and POST is the core of the design. A GET to your unsubscribe URL might come from a security scanner, an antivirus gateway, or a preview fetcher, so it should never remove anyone by itself. A POST with the one-click body is a deliberate action, sent by the mailbox provider because a person asked to leave. ## What RFC 8058 Actually Requires The standard is short, and its requirements are specific.
If you are building or reviewing an unsubscribe system, these are the points that matter. - **An HTTPS URI in List-Unsubscribe.** One-click unsubscribe works only with an `https:` URI. A `mailto:` entry can be included as well, but it does not provide one-click behavior. - **The List-Unsubscribe-Post header with the exact value.** The header must read `List-Unsubscribe-Post: List-Unsubscribe=One-Click`.
- **A DKIM signature that covers both headers.** The message needs a valid DKIM signature whose signed header list includes `List-Unsubscribe` and `List-Unsubscribe-Post`. This prevents someone from altering the headers in transit and lets the mailbox provider trust that they came from the sender. - **No context needed from the request.** The POST will not carry cookies, login sessions, or HTTP authorization.
The URL itself must identify the recipient and the list, typically through an opaque token. - **No redirects.** The endpoint should not answer the POST with a redirect, because redirected POST requests have historically been unreliable. Process the request and return a success response directly. In practice, that last pair of rules shapes the whole design.
The unsubscribe URL must be self-contained: everything needed to identify who is leaving which list has to be encoded in the link, and the endpoint has to act on it without asking the user to sign in or confirm. ## What Gmail and Yahoo Expect From Bulk Senders In February 2024, Gmail and Yahoo began enforcing a common set of requirements for bulk senders, with Gmail's one-click unsubscribe enforcement following in mid-2024.
Gmail defines a bulk sender as one that has sent close to 5,000 or more messages to personal Gmail accounts in a single day. The unsubscribe-related requirements are: - **Support one-click unsubscribe for marketing and subscribed messages**, using the RFC 8058 headers described above. - **Include a clearly visible unsubscribe link in the message body.** The header does not replace the footer link.
- **Process unsubscribe requests within two days.** A request that arrives today should stop mail to that address quickly, not at the end of the next campaign cycle.
These requirements sit alongside the rest of the bulk sender rules: authenticate with SPF and DKIM, publish a DMARC record for the sending domain, align the visible From domain with SPF or DKIM, and keep the spam complaint rate reported in Google Postmaster Tools below 0.3 percent, ideally well under 0.1 percent. Microsoft has since announced similar authentication expectations for high-volume senders to Outlook.com addresses and also recommends functional unsubscribe links. The two are connected.
One-click unsubscribe is one of the most effective ways to keep complaint rates low, because it gives unhappy subscribers a clean exit that is as easy as the spam button. ### Which messages need it The requirement targets marketing and subscribed messages: newsletters, promotions, product announcements, re-engagement campaigns, and similar mail that people chose to receive and can choose to stop.
Transactional messages such as password resets, receipts, and security alerts are generally not expected to carry one-click unsubscribe, because the recipient cannot meaningfully opt out of them. This is one more reason to keep transactional and marketing streams separate, with clear rules for which templates belong in which stream. ## Designing the Unsubscribe Endpoint The endpoint behind the header is a small piece of software, but it carries a lot of responsibility.
A well-built one is fast, idempotent, safe against abuse, and honest with the subscriber. ### Build a self-contained token Each message should carry a unique unsubscribe URL that identifies the recipient and the list or stream without exposing the email address in plain text. A common approach is an opaque token stored in your database or a signed value that your server can verify.
The token should map to the recipient, the list or brand, and ideally the campaign that generated it, which helps reporting. Avoid putting raw email addresses in the URL. Unsubscribe links get forwarded, logged by proxies, and copied into support tickets. An opaque token limits what anyone can learn or abuse.
### Treat GET and POST differently Your single URL will receive two kinds of traffic: - **POST with the body `List-Unsubscribe=One-Click`** comes from a mailbox
Related Articles
Customers do not experience your channels separately. They experience one brand that either feels coordinated or chaotic.
Plain text or HTML is rarely the real choice. Learn why most bulk email should be multipart, what makes a good plain-text part, when plain-looking email wins, and how to build HTML
Most email A/B tests crown winners that don't last. Learn how to test one variable at a time, pick a metric and guardrails before you send, size your sample, split your list
Black Friday and Cyber Monday reward email programs that prepare. Learn how to authenticate, clean and segment your list, ramp volume, and send without landing in spam.
Accessible emails reach more readers and survive image blocking, dark mode, and small screens. Learn how to write alt text, meet WCAG contrast ratios, structure headings and layout
Sending through more than one email provider adds resilience and lowers cost, but only with stable routing, warm fallbacks, shared suppression, and honest measurement.
Learn how to build a seed panel, read inbox vs spam results, and turn placement signals into fixes—without confusing delivery with engagement.
Transactional email keeps products working. Learn how to run Amazon SES transactional mail as infrastructure—auth, warm-up, and monitoring.
Explore SESender
SESender brings audience preparation, contact validation, sender and provider controls, scheduling, delivery tracking, and campaign reporting into one workspace. Review the current product and pricing information before deciding whether the platform fits your messaging workflow.
Explore the platform or review pricing.