The one-click unsubscribe requirement aims to reduce spam complaints by making it easy for recipients to opt out. When unsubscribing is difficult, recipients mark emails as spam instead. Easy unsubscribe protects both the recipient experience and your sender reputation.
Technical Requirements
To comply with the one-click unsubscribe requirement, your emails must include two headers:
List-Unsubscribe Header
Contains an HTTPS URL that handles the unsubscribe request:
List-Unsubscribe: <https://example.com/unsubscribe?id=abc123>List-Unsubscribe-Post Header
Indicates that the URL supports HTTP POST requests for one-click unsubscribe:
List-Unsubscribe-Post: List-Unsubscribe=One-ClickComplete Header Example
List-Unsubscribe: <https://example.com/unsubscribe?id=abc123>
List-Unsubscribe-Post: List-Unsubscribe=One-ClickDKIM Signature Required
Both List-Unsubscribe headers must be covered by your DKIM signature. This prevents attackers from adding or modifying unsubscribe URLs in your emails.
How It Works
- Your email includes both List-Unsubscribe headers
- Gmail/Yahoo displays an unsubscribe button near the sender name
- When clicked, the mailbox provider sends an HTTP POST request to your URL
- Your server processes the request and unsubscribes the user
- No user interaction is required beyond the initial click
What Your Endpoint Must Do
Your unsubscribe URL must:
- Accept HTTP POST requests
- Process the unsubscribe without requiring login
- Process without requiring confirmation or additional steps
- Complete the unsubscribe within 48 hours (Google recommends 2 days)
- Return an HTTP 200 response to confirm success
Which Emails Need One-Click Unsubscribe?
Required For
- Marketing emails
- Promotional messages
- Newsletters
- Sales communications
Not Required For
- Order confirmations
- Shipping notifications
- Password resets
- Account alerts
- Other purely transactional messages
Benefits of Easy Unsubscribe
Lower Spam Complaints
When unsubscribing is easy, recipients use it instead of clicking "Report Spam." This directly protects your sender reputation and spam rate metrics.
Better List Quality
Subscribers who want to leave should leave. Keeping unengaged subscribers hurts your engagement metrics and deliverability.
Compliance
Meeting the requirement prevents enforcement actions from Gmail and Yahoo, protecting your overall deliverability.
Implementation Tips
Use Unique Identifiers
Include a unique identifier in the unsubscribe URL that maps to the specific recipient. This allows processing without additional user input.
Handle Edge Cases
Your endpoint should gracefully handle already-unsubscribed users and invalid identifiers without returning errors.
Log Unsubscribe Requests
Keep records of when and how users unsubscribed. This helps with compliance and debugging.
Test Thoroughly
Send test emails and verify the unsubscribe button appears. Test that clicking it successfully processes the request.
Common Mistakes
Missing List-Unsubscribe-Post Header
The List-Unsubscribe header alone is not sufficient. Without List-Unsubscribe-Post, mailbox providers may fall back to loading the URL in a browser, which is not one-click.
Requiring Confirmation
Do not require users to confirm their unsubscribe choice. The single click should be sufficient.
Requiring Login
Do not require authentication. The URL must work without the user being logged in.
Slow Processing
Process unsubscribes promptly. Sending emails to someone who has unsubscribed damages your reputation and may violate regulations.