Contents
- Why one-click unsubscribe matters
- The two required headers
- The exact List-Unsubscribe=One-Click value
- Why RFC 8058 needs two headers
- The HTTPS-only URL requirement
- Why both headers must be DKIM-signed
- Marketing mail, not transactional
- The enforcement timeline and 550 5.7.515
- Building the unsubscribe endpoint
- The 48-hour processing window
- When one-click does not work
Why one-click unsubscribe matters
The one-click unsubscribe, standardized by RFC 8058, is a requirement that an operator running marketing mail through PowerMTA cannot treat as optional. The bulk sender rules from Gmail and Yahoo, in force since 2024, and from Microsoft since 2025, require it for marketing mail from bulk senders. Getting it wrong means degraded inbox placement or, as of the Microsoft enforcement, outright rejection.
This guide exists because one-click unsubscribe is more subtle than it first appears. It is not a single header but two working together, the exact value of one of them matters character-for-character, both must be DKIM-signed, the URL must be HTTPS, and the implementation extends beyond the headers to a working endpoint and a processing commitment. The structure of this guide: why one-click matters, the two required headers, the exact List-Unsubscribe=One-Click value, why RFC 8058 needs two headers, the HTTPS-only requirement, the DKIM-signing requirement, the marketing-versus-transactional scope, the enforcement timeline including the Microsoft 550 5.7.515 error, building the unsubscribe endpoint, the 48-hour processing window, and the diagnostic workflow when one-click does not work.
The two required headers
RFC 8058 one-click unsubscribe requires two headers working together: List-Unsubscribe and List-Unsubscribe-Post.
| Header | Carries |
|---|---|
| List-Unsubscribe | The unsubscribe mechanism, an HTTPS URL (optionally also a mailto) |
| List-Unsubscribe-Post | The one-click signal, value List-Unsubscribe=One-Click |
List-Unsubscribe carries the actual unsubscribe mechanism. For RFC 8058 compliance it must contain at least one HTTPS URL, the URL that processes the opt-out. It can optionally also include a mailto address, but the HTTPS URL is the part that matters for one-click.
List-Unsubscribe-Post is the header that actually signals one-click capability. Its value must be exactly List-Unsubscribe=One-Click. This header tells the receiving mailbox provider that it may perform an HTTP POST to the URL for a direct, in-client unsubscribe.
An example of the two headers on a marketing message:
List-Unsubscribe: <https://example.com/unsubscribe/9f2c4a8e>
List-Unsubscribe-Post: List-Unsubscribe=One-ClickBoth headers must be present. The List-Unsubscribe header alone, without List-Unsubscribe-Post, does not provide one-click: the receiver does not know it may POST, and treats the URL as an ordinary link rather than offering the in-client one-click action. The two headers together are what RFC 8058 compliance requires.
The exact List-Unsubscribe=One-Click value
The value of the List-Unsubscribe-Post header must be exactly List-Unsubscribe=One-Click. This deserves emphasis because it is a place where otherwise-careful implementations quietly fail.
The exact value is not decorative and not approximate. RFC 8058 defines List-Unsubscribe=One-Click as the specific signal that tells the receiver it can perform an HTTPS POST for a direct unsubscribe. A value that is close but not exact, a different capitalization, extra spaces, a slightly different string, does not carry the signal, and the receiver does not recognize it as one-click capability.
List-Unsubscribe-Post must carry exactly the string List-Unsubscribe=One-Click. This is one of the most common places an otherwise-correct one-click implementation quietly misses the point. The receiver looks for that exact value; anything else, even a minor variation in capitalization or spacing, means the receiver does not see a one-click signal and treats the message as not having one-click. When configuring PowerMTA to add this header, set the value precisely and verify it on a delivered test message.
When the List-Unsubscribe-Post header carries the exact value, and the List-Unsubscribe header carries an HTTPS URL, and both are DKIM-signed, the receiver recognizes the one-click capability and offers the recipient the in-client unsubscribe action. Get the value exact; it is a small detail with a complete-failure consequence.
Why RFC 8058 needs two headers
It is worth understanding why RFC 8058 uses two headers and the POST mechanism, rather than just a single unsubscribe link, because the reasoning explains why the implementation must be exact.
The List-Unsubscribe header has existed for a long time, carrying an unsubscribe URL or mailto. But a plain URL has a problem in the modern email environment: mailbox providers and security tools sometimes prefetch URLs in messages, scanning them for safety. If the unsubscribe mechanism were just a URL that responded to a GET request, that automated prefetching could trigger an unsubscribe accidentally, opting a recipient out of a list they never chose to leave.
RFC 8058 solves this with the POST mechanism. The List-Unsubscribe-Post header signals that the one-click unsubscribe is performed via an HTTP POST, not a GET, with the specific body. Automated URL prefetching uses GET requests; it does not POST. So the POST mechanism lets the mailbox provider offer a genuine in-client unsubscribe action, triggered deliberately by the recipient clicking the provider's unsubscribe button, without the risk that a security scanner's URL prefetch accidentally unsubscribes someone.
This is the design logic: two headers, the exact signal value, and the POST mechanism together provide a real one-click experience that is safe from accidental triggering. The exactness the implementation requires is in service of that design, the receiver needs the precise signal to know it is dealing with a deliberate, POST-based, RFC 8058 one-click and not just a link.
The HTTPS-only URL requirement
The URL in the List-Unsubscribe header must use HTTPS. An HTTP URL fails the RFC 8058 requirement even if the unsubscribe technically functions.
The HTTPS requirement exists for the security and integrity of the unsubscribe request: HTTPS protects the request in transit, which matters because the unsubscribe URL frequently carries an identifier of the recipient and the list. An HTTP URL would expose that, and the mailbox providers require HTTPS for compliance.
The practical consequence: the unsubscribe endpoint must be served over HTTPS, with a valid TLS certificate. An operator implementing one-click must have the unsubscribe endpoint on an HTTPS URL, not HTTP. A List-Unsubscribe header pointing at an HTTP URL is non-compliant, and the mail is treated as not having proper one-click, with the deliverability consequences that follow.
This is straightforward to get right, modern web infrastructure is HTTPS by default, but it is worth checking explicitly: the URL the List-Unsubscribe header carries must begin with https://, and the endpoint must genuinely serve over HTTPS with a valid certificate.
Why both headers must be DKIM-signed
Both the List-Unsubscribe and List-Unsubscribe-Post headers must be covered by a valid DKIM signature. If they are not DKIM-signed, mailbox providers may ignore the headers entirely, even if everything else about them is correct.
The reason is integrity. The one-click headers tell the receiver to perform an unsubscribe action against a URL. The receiver needs assurance that those headers genuinely came from the sender and were not injected or altered by an intermediary. DKIM provides that assurance: a header covered by the DKIM signature is verified as part of the authenticated message. A header not covered by the signature could have been added or changed in transit, so a cautious receiver disregards unsigned control-relevant headers.
For PowerMTA, this means the DKIM signing must cover the List-Unsubscribe and List-Unsubscribe-Post headers. PowerMTA's DKIM signing, via the domain-key directive, signs a set of headers, and that set must include the two one-click headers. If the headers are added to the message after DKIM signing, or are not in the signed header set, they are not protected by the signature, and receivers may ignore them.
The practical sequencing point: the one-click headers must be present on the message before PowerMTA performs DKIM signing, and the signed-header configuration must include them, so the signature covers them. An implementation where the headers are correct but not signed produces the frustrating outcome of receivers ignoring a technically-correct one-click setup.
Marketing mail, not transactional
The one-click unsubscribe requirement applies to marketing and promotional email, not to transactional email.
The bulk sender rules require one-click for promotional and commercial messaging, the newsletters, marketing campaigns, and subscription mail. Transactional messages, password resets, receipts, shipping confirmations, reservation confirmations, account alerts, are not the target, because a recipient does not unsubscribe from their own password reset.
| Mail type | One-click headers |
|---|---|
| Marketing campaigns, newsletters | Required |
| Subscription / promotional mail | Required |
| Password resets, receipts, confirmations | Not required |
| Account alerts, operational notifications | Not required |
This distinction has a practical consequence: the first step in implementing one-click is not to add the headers to every message, it is to identify which streams are actually promotional or subscription mail. The one-click headers belong on the marketing streams.
For a PowerMTA deployment that handles both transactional and marketing traffic, frequently through separate streams or separate VMTA pools, the one-click headers are configured for the marketing stream. The recipient-facing logic should match: a marketing email gets the one-click headers and a working unsubscribe; a transactional email does not need them.
One clarification: this scoping applies specifically to the one-click unsubscribe requirement. The other bulk sender requirements, authentication with SPF, DKIM, and DMARC, apply to transactional mail too. It is only the one-click unsubscribe that is scoped to marketing mail.
The enforcement timeline and 550 5.7.515
The one-click unsubscribe requirement has been enforced progressively by the major mailbox providers.
| Provider | Enforcement | Non-compliance consequence |
|---|---|---|
| Gmail | Phased through 2024 | Spam folder or rejection |
| Yahoo | Phased through 2024 | Spam folder or rejection |
| Microsoft | From May 2025 | Junk folder or 550 5.7.515 rejection |
Gmail and Yahoo rolled out enforcement in phases through 2024, giving senders time to implement the changes. Non-compliant marketing mail from bulk senders faces spam-folder placement or rejection.
Microsoft joined the enforcement starting May 2025. Non-compliant bulk-sender mail to Microsoft now routes to the Junk folder or gets rejected outright with the error code 550 5.7.515. An operator who sees 550 5.7.515 rejections from Microsoft on their marketing mail is hitting the Microsoft bulk sender enforcement, and a missing or broken one-click implementation is a likely cause alongside the authentication requirements.
The trajectory is clear: one-click unsubscribe for bulk-sender marketing mail is enforced by all three major providers, and the enforcement has hardened from soft (spam placement) to hard (rejection). An operator running marketing mail through PowerMTA must have a correct one-click implementation; it is no longer a best practice that improves deliverability, it is a requirement whose absence causes rejection.
Building the unsubscribe endpoint
The headers are only half of one-click; the other half is the endpoint that receives the POST and actually unsubscribes the recipient.
When a recipient clicks the unsubscribe button their mailbox provider shows, the provider sends an HTTP POST to the URL in the List-Unsubscribe header. The POST body carries List-Unsubscribe=One-Click. The endpoint must receive that POST and complete the unsubscribe.
The requirements for the endpoint:
- It must accept the POST. The endpoint must handle an HTTP POST request, not only a GET. The provider sends a POST.
- It must complete the unsubscribe immediately. On receiving the POST, the endpoint unsubscribes the recipient. No confirmation page, no second click, no login. The one-click experience means the opt-out is done on the single POST.
- It must identify the recipient and list from the URL. The URL in the List-Unsubscribe header must carry enough information for the endpoint to know which recipient to unsubscribe from which list.
- It must serve over HTTPS with a valid certificate.
An illustrative endpoint, in concept, receives the POST, extracts the identifying token from the URL, looks up the recipient and list, and marks the recipient unsubscribed:
# Conceptual unsubscribe endpoint behavior
# POST /unsubscribe/<token>
# body: List-Unsubscribe=One-Click
def handle_unsubscribe(token):
record = lookup_token(token) # recipient + list
if record:
mark_unsubscribed(record.recipient, record.list)
return 200 # no confirmation page, just succeedRFC 8058 recommends the URL carry an opaque or hard-to-forge identifier, a token, rather than relying on a plain email address in the URL. A token that the endpoint maps to the recipient and list is more secure: it does not expose the email address in the URL, and it cannot be trivially forged to unsubscribe arbitrary addresses.
If the unsubscribe endpoint responds to the POST with a confirmation page, or requires the recipient to take another step to complete the opt-out, the implementation is no longer one-click. The whole point of RFC 8058 one-click is that the single POST completes the unsubscribe. An endpoint that shows a confirmation page or requires a second click loses the one-click experience the mailbox providers require, and the implementation is non-compliant even though the headers are correct. The endpoint must complete the opt-out on the POST and simply succeed.
The 48-hour processing window
RFC 8058 one-click compliance includes a processing-time commitment: unsubscribe requests must be honored within 48 hours.
When a recipient clicks unsubscribe, the mailbox provider POSTs to the endpoint, and the sender is responsible for processing that unsubscribe, actually removing the recipient from the list, within 48 hours. Both Gmail and Yahoo specify this 48-hour window, and the providers' guidance recommends acting faster when possible, because delayed processing signals poor list management.
The practical meaning: if a recipient clicks unsubscribe on a Monday, they must not receive another email from that list by Wednesday. The unsubscribe must be reflected in the sending list within the 48-hour window.
This window is part of why the endpoint and the processing pipeline matter as much as the headers. A correct header implementation and a working endpoint that receives the POST are not enough on their own; the unsubscribe the endpoint records must flow through to the actual sending list within 48 hours, so the next campaign does not send to the unsubscribed recipient. For a PowerMTA deployment, this means the suppression of the unsubscribed recipient must be reflected before the next send to that list, and the pipeline from the unsubscribe endpoint to the suppression list must be prompt.
An operator whose one-click headers are perfect but whose unsubscribe processing lags beyond 48 hours is still non-compliant in substance, and continuing to mail recipients who unsubscribed both violates the requirement and generates spam complaints from the annoyed recipients.
When one-click does not work
When one-click unsubscribe is not working, the diagnostic workflow:
Step 1: inspect the headers on a delivered message. Send a test marketing message and inspect its full headers at the recipient. Confirm both List-Unsubscribe and List-Unsubscribe-Post are present.
Step 2: verify the exact List-Unsubscribe-Post value. The value must be exactly List-Unsubscribe=One-Click. Check it character-for-character; a variation here is a common silent failure.
Step 3: verify the URL is HTTPS. The URL in List-Unsubscribe must begin with https://. An HTTP URL fails compliance.
Step 4: verify DKIM coverage. Confirm the DKIM signature covers both one-click headers. If they are not in the signed header set, receivers may ignore them. Check the DKIM-Signature header's signed-header list.
Step 5: test the endpoint. Send an HTTP POST to the unsubscribe URL with the body List-Unsubscribe=One-Click, as the mailbox provider would. Confirm the endpoint accepts the POST, completes the unsubscribe, and does not return a confirmation page or require another step.
Step 6: verify the recipient is actually removed. After the test POST, confirm the test recipient is genuinely unsubscribed from the intended list, and that the suppression flows through to the sending list.
Step 7: check the stream scope. Confirm the one-click headers are on the marketing streams. If they are missing from a marketing stream, that stream is non-compliant.
Step 8: check the processing window. Confirm the pipeline from the unsubscribe endpoint to the actual suppression honors the 48-hour window, so unsubscribed recipients are not mailed again.
An operator we worked with had implemented one-click unsubscribe for their marketing mail and believed it was working: the List-Unsubscribe header was present with a proper HTTPS URL, the List-Unsubscribe-Post header was present, the unsubscribe endpoint accepted POSTs and completed the opt-out cleanly, the headers were DKIM-signed, and the processing pipeline honored the 48-hour window. Everything was, as far as they could tell, correct. Yet their marketing mail was steadily losing inbox placement, and after the Microsoft enforcement began they started seeing 550 5.7.515 rejections from Microsoft. They were puzzled, because their one-click looked complete. We inspected the actual headers on a delivered message. The List-Unsubscribe header was fine. The List-Unsubscribe-Post header was present, but its value was not exactly right. RFC 8058 requires the exact string List-Unsubscribe=One-Click, and their implementation was emitting a value with a subtly different capitalization in one word. To a human reader it looked correct; to the mailbox providers' parsers, which match the exact defined string, it did not carry the one-click signal at all. So the receivers saw the List-Unsubscribe-Post header, found a value they did not recognize as the RFC 8058 one-click signal, and treated the message as not having one-click. Every other part of the implementation, the HTTPS URL, the DKIM signing, the working endpoint, the 48-hour processing, was perfect, and all of it was undermined by a single wrong character in the one header value. The fix was trivial once identified: emit the value as exactly List-Unsubscribe=One-Click. Once the value was exact, the receivers recognized the one-click capability, the Microsoft rejections stopped, and inbox placement recovered. The lesson is the one about the exact value: RFC 8058 defines List-Unsubscribe=One-Click as a precise string, the receivers match it precisely, and an implementation that is correct in every other respect fails completely if that value is even slightly off. When one-click does not work and everything looks right, check the List-Unsubscribe-Post value character-for-character.
RFC 8058 one-click unsubscribe is a hard requirement for marketing mail from bulk senders, enforced by Gmail, Yahoo, and Microsoft, with non-compliance now causing rejection rather than just degraded placement. Correct implementation has several exact requirements: both the List-Unsubscribe and List-Unsubscribe-Post headers present, the List-Unsubscribe-Post value exactly List-Unsubscribe=One-Click, an HTTPS URL, both headers covered by the DKIM signature, the headers on the marketing streams and not needed on transactional mail, an endpoint that accepts the POST and completes the opt-out immediately without a confirmation page, and the unsubscribe honored within 48 hours. A failure in any one of these makes the implementation non-compliant, and several of them, the exact header value especially, fail silently. Operators running marketing mail through PowerMTA should treat one-click as a precise, end-to-end implementation, the exact headers, DKIM-signed, with a working endpoint and prompt processing, and verify it on real delivered messages, because a one-click setup that is correct in every respect but one still fails completely.