RFC 8058 one-click unsubscribe: headers and implementation

RFC 8058 lets an inbox provider unsubscribe a recipient by sending an HTTPS POST request without taking the recipient to a confirmation page. Gmail requires it for marketing and subscribed messages from bulk senders; Yahoo requires easy unsubscribe for bulk marketing and subscribed mail. Ordinary transactional messages such as password resets and receipts are excluded.

The protocol is defined in RFC 8058. Also check the current Gmail sender guidelines and Yahoo sender requirements.

TL;DR

• Add both List-Unsubscribe and List-Unsubscribe-Post: List-Unsubscribe=One-Click headers.
• Include an HTTPS URL in List-Unsubscribe; mailto: can be a fallback but does not meet Gmail's one-click requirement alone.
• Make the body unsubscribe link obvious on subscription messages.
• Process requests immediately and enforce suppression for the relevant subscription list within 48 hours.
• Test in staging with real headers and in production with feedback loop/complaint monitoring.

RFC 8058 headers to copy-paste

Use an opaque, signed HTTPS URL. When the mailbox provider sends a POST, return a successful response and suppress the subscription without asking for confirmation.

List-Unsubscribe: <https://example.com/unsub/abcd1234>, <mailto:[email protected]?subject=unsubscribe>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

A mailto-only List-Unsubscribe header can offer a manual unsubscribe path, but it is not RFC 8058 one-click and must not be paired with a claim that it meets Gmail's HTTPS one-click requirement.

What “process within 2 days” means in practice

• Immediate action: Suppress the address from the subscription list represented by the token. Do not wait for batch jobs.
• Correct scope: Suppress the recipient from the list represented by the token. Offer a separate global option, but do not silently suppress essential transactional messages.
• Latency target: Aim for near real-time (seconds). The 48-hour SLA is a ceiling, not a goal.
• Audit trail: Log the request (timestamp, list ID, IP, user agent) so you can prove compliance if challenged.

Implementation tips that reduce complaints

• Accept an unauthenticated HTTPS POST with the body List-Unsubscribe=One-Click; do not require cookies, a login, or a confirmation step.
• A browser GET may show a confirmation or preference page, but it must not unsubscribe automatically because security scanners often visit links.
• Honor list-level and global choices: offer “unsubscribe from this list” and “unsubscribe from all,” including product announcements and policy notices where allowed.
• Use opaque signed tokens that identify the recipient and list without exposing an email address. Keep them valid long enough for recipients to act on older messages.
• Rate-limit the endpoint lightly to prevent abuse but never block legitimate clicks.
• Include a friendly reply-to mailbox; sometimes users will write back instead of clicking.

Testing and monitoring checklist

• Validate headers exist on the final message (not just in your ESP template).
• POST the exact RFC 8058 form body to the HTTPS endpoint and confirm immediate list suppression.
• Send a follow-up test campaign within 24 hours to ensure the unsubscribed address is excluded.
• Monitor spam complaint rates; one-click support should push them below 0.1%.

Common failure modes

• Missing List-Unsubscribe-Post header because the ESP toggle is off for a specific list.
• The endpoint expects GET, cookies, authentication, or a CSRF token instead of accepting the provider's POST.
• The token does not identify a list, so one request suppresses too little or blocks unrelated transactional mail.
• Mailto handler points to a shared mailbox nobody checks.

Where SMTP Zen helps

SMTP Zen focuses on strong authentication, clean routing, and reliable headers so your transactional and professional mail stays welcome in inboxes. Pair it with your own suppression and unsubscribe handling to meet Gmail/Yahoo expectations without bolting on a marketing stack.