How one-click unsubscribe works
When you receive email from a newsletter or mailing list, Cleanbox automatically detects the subscription and gives you a one-toggle unsubscribe option on the contact page. This article explains how the detection works, what happens when you unsubscribe, and what to do when it does not work.
How subscriptions are detected
Cleanbox looks for the List-Unsubscribe header in incoming emails. This is a standard email header (defined in RFC 2369 and RFC 8058) that legitimate senders include to provide a machine-readable unsubscribe mechanism.
When Cleanbox finds this header, it extracts:
- The unsubscribe URL (an HTTP/HTTPS link the sender provides)
- Whether the sender supports one-click unsubscribe (RFC 8058) — indicated by a
List-Unsubscribe-Postheader - An optional mailto address as fallback
- A subscription identifier to track multiple lists from the same sender
Subscriptions appear on the contact detail page. Each subscription shows when it was first and last seen, its current status (active, unsubscribed, or failed), and a toggle to unsubscribe.
What happens when you unsubscribe
When you toggle a subscription off, Cleanbox sends a request directly to the sender:
- If the sender supports one-click (RFC 8058) — Cleanbox sends an HTTP POST request to the unsubscribe URL with the body
List-Unsubscribe=One-Click. This is the fastest and most reliable method. Most major email senders (Mailchimp, SendGrid, Amazon SES, etc.) support this. - If the sender only provides a URL — Cleanbox sends an HTTP GET request to the unsubscribe URL. This typically loads the sender's unsubscribe confirmation page, which may or may not complete the unsubscription automatically.
After the request:
- If the request succeeds, the subscription status changes to unsubscribed and the timestamp is recorded.
- If the request fails (timeout, server error, invalid URL), the status changes to failed. You can try again later or visit the unsubscribe link manually.
Three subscription statuses
| Status | Meaning |
|---|---|
| Active | You are currently subscribed. Toggle off to unsubscribe. |
| Unsubscribed | Cleanbox successfully sent the unsubscribe request. The sender should stop sending within a few days (CAN-SPAM allows up to 10 business days). |
| Failed | The unsubscribe request could not be completed. The sender's server may have been unreachable or returned an error. |
When unsubscribe is not available
Not all senders include the List-Unsubscribe header. If you do not see a subscription toggle for a sender, it means:
- The sender does not include unsubscribe headers (common with older systems or spam)
- The email is transactional rather than marketing (order confirmations, security alerts, etc.)
In these cases, you can:
- Change the contact state to blocked to reject all future emails from this sender
- Create a filter to deny emails matching specific criteria
- Look for an unsubscribe link in the email body and use it manually
Important notes
- Unsubscribing does not happen instantly on the sender's side. Most senders process unsubscribe requests within 24-48 hours, but legally they have up to 10 business days.
- Some senders have multiple mailing lists. Unsubscribing from one list does not necessarily unsubscribe you from all of them. Each list appears as a separate subscription in Cleanbox.
- Cleanbox validates unsubscribe URLs before sending requests — private IP addresses, localhost, and internal domains are rejected for security.
