List-Unsubscribe
One-click unsubscribe headers that let a mailbox provider act on the user’s behalf, cutting complaints and expected of bulk senders.
List-Unsubscribe and List-Unsubscribe-Post let a mailbox provider offer one-click unsubscribe. It reduces complaints and is required for bulk senders.
List-Unsubscribe and List-Unsubscribe-Post let a mailbox provider offer one-click unsubscribe. It reduces complaints and is required for bulk senders.
Related
The short version
- List-Unsubscribe is a pair of email headers that lets a mailbox provider render its own unsubscribe control beside your message, so the recipient never has to hunt for a footer link.
- RFC 2369 defined the header and allowed a mailto address and a web URI. RFC 8058 added List-Unsubscribe-Post, which turns the web URI into a genuine one-click action with no page load.
- It is a withdrawal mechanism, not a permission record. Opt-in is how you earn the right to send; List-Unsubscribe is how you honour the moment that right ends.
- One-Click means an unauthenticated HTTPS POST whose body is exactly List-Unsubscribe=One-Click, answered with a 2xx status, with no login, no CSRF token and no confirmation screen.
- For Indian senders the hard part is rarely the header. It is propagation: Gmail is the largest consumer inbox, and a day of lag between the click and the suppression is how a polite unsubscribe becomes a spam complaint.
- Measure time-to-suppress and the share of unsubscribes that arrive by POST. An unsubscribe rate on its own tells you nothing about whether the mechanism works.
What the List-Unsubscribe header is, and what it is not
List-Unsubscribe is an optional email header, defined in RFC 2369, whose value is a comma-separated list of URIs wrapped in angle brackets. A mailbox provider that understands the header may show an unsubscribe affordance in its own interface, next to the sender name or inside the overflow menu, and wire that control to one of the URIs. The recipient never sees the header. They see a button that belongs to their mail client, which is precisely why it works: the control sits where the irritation is, not three scrolls down in eight-point grey text.
What it is not: it is not the unsubscribe link in your footer, although the two should lead to the same outcome. It is not a legal notice, not a preference centre, and not evidence that anyone consented in the first place. It is also not a replacement for a suppression list. The header is a channel for a request; the suppression list is the durable record that the request happened and must keep happening.
The distinction matters because teams routinely ship one and believe they shipped the other. A header that points at a page which returns 200 and does nothing is worse than no header at all, because the provider now believes the recipient was served. The header is a promise about behaviour, and the behaviour lives on your server.
RFC 2369 and RFC 8058 do two different jobs
RFC 2369, published in 1998, described a family of list headers: List-Help, List-Subscribe, List-Unsubscribe, List-Post, List-Owner and List-Archive. The unsubscribe value could be a mailto URI, an http URI, or both. For two decades the common implementation was a mailto address that opened a pre-addressed message, or a web link that opened a page where the recipient confirmed. Both are legitimate. Neither is one click, and both lose people at the confirmation step.
RFC 8058, published in 2017, added the missing piece: a signal that says this URI accepts a machine-generated POST and that the action is complete when the POST succeeds. It introduced the List-Unsubscribe-Post header with the fixed value List-Unsubscribe=One-Click, and it requires that the corresponding List-Unsubscribe URI be HTTPS. The provider does not open a browser, does not ask the recipient anything further, and does not wait for a confirmation email. It sends the request and trusts the status code.
The practical difference is a step count. A 2369 link is a journey: click, page load, maybe a survey, maybe a login, maybe a confirmation. An 8058 POST is a single state change. Every abandoned journey in the first model becomes either a complaint or a silent reader who stays on the list, and both are worse than an unsubscribe.
The one-click contract, header by header
A conforming pair of headers looks like this in the raw message: List-Unsubscribe with an HTTPS URI in angle brackets, optionally followed by a mailto URI, and List-Unsubscribe-Post with the literal value List-Unsubscribe=One-Click. The HTTPS URI must be reachable without authentication and must accept a POST. The mailto URI, if present, remains useful for clients that never implemented the POST path, and for recipients who prefer to reply.
The POST that arrives carries the content type application/x-www-form-urlencoded and a body of exactly List-Unsubscribe=One-Click. There is no session, no cookie, no CSRF token and no referrer you can trust. Some providers add a user agent you can log. Most send nothing else. This means the recipient must be identified entirely by the URI itself, which is why the token in the path has to be unguessable and long-lived enough to survive a message sitting in an inbox for a year.
The provider may only offer the control when authentication passes, which is one reason the header is often implemented and never seen. If your DKIM signature is broken, or your DMARC policy is p=none with an alignment failure on this stream, the mailbox provider has less reason to trust that you are the sender you claim to be, and the unsubscribe affordance is the first thing it drops.
What the POST must do on your side
The endpoint has four obligations and they are all boring. Resolve the token to a recipient and a scope. Write the suppression with a timestamp and a source of post. Return a 2xx status quickly, without redirecting and without requiring any further interaction. Make the operation idempotent, because providers retry and because a recipient may click twice in two different clients. A 302 to a confirmation page breaks the contract even if a human would eventually land somewhere sensible.
Scope is where most implementations quietly fail. If the token says unsubscribe from the Diwali campaign, and the recipient also sits in four other lists, you have honoured the letter and missed the intent. The token should identify the person and the channel, and the write should suppress the person across every marketing stream you operate, while keeping transactional mail available. Someone who unsubscribes from a newsletter has not asked to stop receiving their invoice.
Speed matters more than elegance. The mailbox provider is not going to check back. If your endpoint writes to a queue that is drained hourly, the recipient may receive another campaign before the suppression lands, and the second message is the one that gets reported as spam. Write the suppression synchronously to the source of truth, then fan out to the CRM, the warehouse and the ad audiences asynchronously.
Withdrawal is not acquisition, and the difference is legal
Opt-in answers the question: may we contact this person, for this purpose, on this channel, starting now. List-Unsubscribe answers a different question: this person has withdrawn, how fast can we stop. Confusing the two produces two familiar bugs. A team treats a header as consent evidence and cannot show when permission was given. Or a team treats an unsubscribe as a preference downgrade and moves the person to a monthly digest, which is not what was asked for.
Under India’s Digital Personal Data Protection Act 2023, consent must be free, specific, informed and given by clear affirmative action, and withdrawal must be as easy as giving it. Section 8 also requires the fiduciary to erase data on withdrawal unless retention is required by law. A one-click header is the clearest possible way to satisfy the ease-of-withdrawal duty for email, and it produces a timestamped record that a preference-centre survey never would.
The near-neighbours are worth naming. A preference centre lets someone choose topics, and it is a good thing to offer, but it cannot be the only path, because a person who wants out of everything should not have to navigate a matrix. A suppression list is the record, not the interface. A feedback loop complaint is a signal from the provider after the fact, not a request from the person. List-Unsubscribe is the request path, and it should be the shortest one you own.
Why mailbox providers care about your unsubscribe
A mailbox provider has one scarce resource, which is attention, and one metric it defends, which is how often its users mark mail as spam. Every message that a person does not want is a small liability. A working one-click control converts a spam report into an unsubscribe, and an unsubscribe is a clean outcome for everyone: the sender loses a low-value contact, the provider loses a complaint, and the recipient stops being annoyed.
Google’s bulk sender guidelines make this explicit. Senders above roughly five thousand messages a day to Gmail accounts are expected to authenticate with SPF, DKIM and DMARC, to offer one-click unsubscribe on promotional and marketing mail using List-Unsubscribe and List-Unsubscribe-Post, and to honour the request within two days. The guidelines also set a spam rate threshold in Postmaster Tools. Yahoo published a similar set of expectations for bulk senders. These are published requirements, not folklore, and they apply to Indian senders in exactly the same way as to anyone else.
Two days is a ceiling that exists because some senders batch. It is not a target. A request that takes 36 hours to take effect will, in a weekly campaign cadence, produce at least one more unwanted message. The number to watch is not compliance with the deadline, it is the p95 time between the click and the last system that could send to that address knowing about it.
Implementing it when four systems can send mail
Most Indian mid-market companies do not have one sender. They have a marketing platform, a transactional provider attached to the product, a CRM that can send one-off sequences, and a support tool that emails tickets. The header only helps if all four consult the same suppression service at send time. Checking at list-build time is the classic error: the list was built on Monday, the unsubscribe arrived on Tuesday, the send went out on Wednesday, and the contact receives a message they explicitly cancelled.
The design that survives is small. A suppression service owns a table keyed by a normalised address hash, with columns for scope, reason, source, timestamp and the campaign that triggered it. Every sender calls a single lookup endpoint, or reads a replicated view, immediately before handing a message to the MTA. The unsubscribe endpoint writes to that service first and returns 2xx only after the write commits. Everything else, the CRM field, the analytics event, the ad audience exclusion, is downstream and allowed to lag.
Tokens should be HMAC-signed over the contact identifier, the channel and a schema version, with the signature in the path so that no query string parsing is required. Do not put an email address in the URL. Do not use a token that expires in 30 days, because people unsubscribe from old mail months later and an expired token turns into a 410 that the provider records as a failed request. Log every call with the status, the latency and the resolved scope, and alert on any 5xx rate above a fraction of a percent.
India: Gmail dominance, DPDP and the channel next door
The Indian consumer inbox is heavily concentrated. Gmail is the default address for a large share of urban recipients, which means Google’s bulk sender rules are not an international curiosity but the operational baseline for a D2C brand in Bengaluru. Zoho Mail has a meaningful base among small businesses and professionals, RediffMail persists among older consumers, and enterprise Outlook dominates in B2B accounts where the buyer sits behind Microsoft 365. A header that renders in one client and is ignored in another is still worth shipping; you just cannot measure it from a single seed inbox.
The DPDP Act changes the stakes rather than the mechanics. Withdrawal has to be as easy as consent, the notice has to say how to withdraw, and the fiduciary has to erase on withdrawal unless a law requires retention. That last clause is why a marketing unsubscribe is not automatically a deletion request: tax law may require the invoice, and a suppression record with a hashed identifier is itself a legitimate retention, because without it you cannot honour the withdrawal next month.
The adjacent channels have their own rules and should not be silently coupled. On WhatsApp, Meta’s business messaging policy requires an opt-out path in marketing templates, and a recipient who replies STOP has withdrawn from that channel. On SMS, commercial sending in India runs through DLT-registered headers and templates, and the template content and consent record are what the regulator examines. Unsubscribing someone from email is not a mandate to remove them from WhatsApp, and the reverse is also true. Honour the channel that was named, and offer a preference path for the rest.
Measuring the mechanism rather than the mood
The obvious metric, unsubscribe rate, is a ratio of withdrawals to delivered mail, and it moves for reasons that have nothing to do with your endpoint: a bigger campaign to a colder list, a seasonal spike, a competitor’s outage. It is worth tracking, and it is not a measure of whether one-click works. The mechanism metrics are time-to-suppress, the share of withdrawals that arrive as a POST rather than a footer click or a mailto, the error rate on the endpoint, and the number of messages sent to an address after its withdrawal timestamp.
Time-to-suppress should be reported as a distribution, not an average. Take the timestamp on the POST and the timestamp on the last row that any sender could read, and compute p50 and p95 across a week. A mean of twelve minutes can hide a p95 of nine hours caused by one nightly job, and the nightly job is the one that produces the complaint. This is the same percentile discipline you would apply to voice latency, and it is just as often skipped.
Then measure the thing nobody wants to measure: false positives. How many people click unsubscribe and then write to support saying they never subscribed, or that they only wanted fewer emails? A rate near zero is normal. A rate above a couple of percent suggests the list source is dirty, the welcome series is unclear, or the unsubscribe is landing on people who were imported without consent. That is a data acquisition problem surfacing as a preference problem, and the endpoint is merely where it becomes visible.
The mistakes that quietly break one-click
The failures cluster. A login wall, because the token was treated as a session and the flow was built by the web team. A confirmation page, because legal wanted a record and nobody checked the RFC. A token that expires in a month, so a click on an old message returns an error page the provider counts as failure. Only a mailto URI, because the ESP’s default template was never customised. A header present on campaign mail but absent on the automated flows, which are precisely the messages people want to stop.
There are quieter ones. The unsubscribe removes the contact from one list and leaves them in five. The suppression is written but the transactional sender reads a different database. The footer link requires JavaScript, so it works in a browser and fails in a mail client webview. The endpoint returns 200 before the write commits, so a crash between the two produces a silent no-op. And the header is added by a proxy that rewrites the message, breaking the DKIM signature that made the control appear in the first place.
A short pre-flight check catches most of this. Send to a Gmail account and a Microsoft 365 account, confirm the control appears, click it, confirm the POST arrives, confirm the suppression row exists, then trigger a campaign to that address and confirm nothing is delivered. That takes twenty minutes and it is the only test that proves the promise in the header.
Worked example: one hundred thousand emails a month
Take a D2C brand on the Growth plan, which includes 1,00,000 emails a month at ₹7,999 plus 18% GST, or ₹9,438.82 on the invoice. Suppose it sends four campaigns and a welcome flow, and the observed unsubscribe rate is 0.4%, which is 400 withdrawals across the month. If 68% arrive by POST, that is 272 requests that never touched a web page, and each one is a person who would otherwise have needed to find the footer, load a page and press a button.
Now suppose the suppression pipeline writes to the marketing platform immediately but the CRM only refreshes overnight, and the CRM owns a re-engagement sequence that sends at 09:00. A withdrawal at 14:00 on Monday is suppressed for the Tuesday campaign and not for the Tuesday morning sequence. At 400 withdrawals a month, even a 5% leak is 20 unwanted messages, and unwanted messages are the raw material of complaints. Moving the lookup to send time removes the leak entirely and costs one API call per message.
The economics are lopsided. The engineering work is perhaps two days: an endpoint, a suppression table, a lookup in the send path and a dashboard. The alternative is a slow drift in reputation that shows up first as placement in Promotions, then as a higher complaint rate in Postmaster Tools, then as a conversation with a provider about why your volume was throttled. Fixing deliverability after the fact costs far more than the endpoint, and it is much harder to attribute.
Frequently asked questions
Is List-Unsubscribe legally required in India?
The DPDP Act does not name email headers. It requires that withdrawing consent be as easy as giving it, and that the notice explain how to withdraw. A one-click header is strong evidence that you met that duty for email, and it is the practical standard the large mailbox providers enforce regardless of jurisdiction. Treat it as required in practice.
Do I need both the mailto and the HTTPS URI?
The HTTPS URI is what makes one-click possible under RFC 8058. The mailto URI is a fallback for clients that never implemented the POST path and for recipients who prefer to reply. Including both is harmless and slightly widens coverage, but the HTTPS endpoint is the one that has to work correctly, because it carries almost all of the volume.
Why does the unsubscribe button not appear in my test email?
The usual causes are a missing List-Unsubscribe-Post header, an http rather than https URI, a broken DKIM signature, or a provider that only surfaces the control above a volume threshold or after the recipient has engaged. Test with a real Gmail account and check the raw headers first. If the headers are correct and the control is absent, the provider has chosen not to render it.
Should the endpoint require a login?
No. Requiring authentication breaks the one-click contract, because the mailbox provider sends an unauthenticated POST with no session. The security comes from the unguessable signed token in the URI, not from a login. A token that identifies the recipient and the scope, is signed, and is long-lived is the correct design.
What status code should the endpoint return?
A 2xx, quickly, after the suppression has been committed. Avoid redirects to a confirmation page and avoid returning 200 before the write lands, because a crash between response and commit produces a silent failure the provider will never retry. Return 4xx only for a genuinely invalid or expired token, and alert on that rate.
Does unsubscribing from marketing stop transactional email?
It should not. Invoices, password resets, delivery updates and ticket replies are a different purpose with a different basis, and suppressing them would break the service the person is paying for. Scope the token to marketing streams and keep transactional mail on its own path, with its own preference controls where the law requires them.
How quickly must the unsubscribe take effect?
Google’s bulk sender guidelines allow up to two days, and Yahoo’s guidance is similar. That is a compliance ceiling, not an operational target. In practice, suppress synchronously on the request, drain any queued campaign within minutes, and propagate to downstream systems within the hour. The metric that predicts complaints is the p95, not the median.
Is one-click unsubscribe only for bulk senders?
The mechanism is useful at any volume, because it reduces complaints and gives the recipient a clean exit. The published requirement applies to senders above roughly five thousand messages a day to Gmail accounts, and to similar thresholds elsewhere. Below that, one-click is still the right design, and it costs very little once the suppression service exists.
What is the difference between List-Unsubscribe and a suppression list?
The header is a request channel, and the suppression list is the durable record of the outcome. A header without a suppression list produces a control that appears to work and does not. A suppression list without a header still works, but it forces the recipient to find your footer, which is where the spam report happens instead.
Can I use the same endpoint for WhatsApp and SMS opt-outs?
You can share the suppression service but not the endpoint contract. Email one-click is an unauthenticated POST defined by RFC 8058. WhatsApp opt-out is a conversation event, and SMS opt-out runs through DLT-registered templates and TRAI rules. Model withdrawal as a channel-scoped event in one store, and expose a different interface for each channel.