Reviewed and updated: 16 October 2026. Rechecked Gmail and Yahoo scope, RFC 8058, SendGrid settings and the SES v2 header example. Added Google’s 48-hour mitigation consequence and both RFC-supported POST encodings.
Part of: Gmail and Yahoo bulk sender requirements.
One-click unsubscribe lets recipients leave a marketing list through their email client’s unsubscribe control. A hosted email platform can provide the mechanism, but your delivered messages and suppression behavior are what you need to verify.
TL;DR:
- Check the requirements of the receiving provider.
- Look for two headers, their DKIM signature coverage and a working HTTPS POST endpoint.
- Test that unsubscribing prevents later marketing sends.
- Keep a visible unsubscribe link in the email body too.
Who Needs It?
| Provider | Applicable traffic | Current unsubscribe rule |
|---|---|---|
| Personal Gmail | Bulk senders’ marketing and subscribed messages | RFC 8058 HTTPS POST plus a visible body link. Transactional messages are excluded. |
| Yahoo | Bulk marketing and subscribed messages | Functioning list-unsubscribe and a visible body link. RFC 8058 POST is strongly recommended, while mailto: is accepted. |
Gmail’s bulk classification uses about 5,000 messages or more to personal Gmail in 24 hours across the same primary domain. Yahoo publishes no numeric bulk threshold. Google’s FAQ recommends processing unsubscribes within 48 hours and lists failure to do so as a reason delivery support or mitigations are unavailable. Yahoo requires honoring them within two days. Google FAQ, Yahoo requirements, Yahoo scope.
Implement RFC 8058 for marketing lists that reach both providers. Keep subscriptions distinct from receipts, password resets and other essential account communication.
What Happens If It Is Missing?
Google explicitly says it does not automatically reject messages or mark them as spam solely because one-click unsubscribe is missing. The missing feature affects eligibility for delivery mitigation; unwanted mail can also attract complaints and damage later delivery. Google’s current FAQ.
That does not make unsubscribe optional for applicable traffic. It means you should fix the feature without presenting it as a guaranteed explanation for every bounce or spam placement.
Check Your Email Platform
Avoid treating a provider name as proof of compliance. Products, message streams, subscription settings and custom headers can differ within one platform.
| Sending setup | What to verify |
|---|---|
| Managed marketing platform | Whether unsubscribe is enabled for the actual campaign type, and whether it updates the list used by later sends |
| SendGrid | Subscription tracking or your own header implementation. Its documentation says enabled subscription tracking adds both headers. |
| Amazon SES | Whether you use SES subscription management or your own endpoint and headers |
| Custom SMTP or application code | Header creation, DKIM signing, endpoint operation and suppression integration |
Use SendGrid’s documentation and AWS’s implementation guide for those products. For another platform, ask its support team which settings apply to your account and send a real test.
A useful support request is: “Show us a delivered marketing message with RFC 8058 headers, valid signature coverage and a successful unsubscribe that prevents the next campaign send.”
Verify the Whole Operation
- Add a test recipient to the marketing list and send through the production sending path.
- Open the delivered message source. In Gmail, choose Show original from the message menu.
- Check both headers shown below and verify the HTTPS URL identifies the correct subscriber and list.
- Check a passing DKIM signature covers both header names in its
h=list. - Submit a test unsubscribe and check the suppression state.
- Attempt another marketing send to the test subscriber and confirm it is excluded.
A visible unsubscribe button can help with manual testing, but the mailbox provider controls whether it displays that button. Header presence or button appearance alone does not prove the backend works. Google’s unsubscribe guidance.
Technical Implementation Guide
Headers and Signing
Add these before DKIM signing the marketing message:
List-Unsubscribe: <https://mail.example.com/unsubscribe/opaque-list-subscriber-token>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
RFC 8058 requires a valid DKIM signature covering both unsubscribe headers. The URL must support a POST that completes without cookies, HTTP authorization, login or a confirmation page. Do not redirect the POST. Use an opaque, hard-to-forge token that identifies both the subscriber and list. RFC 8058, sections 3 and 4.
For operational reliability, make repeated requests safe, persist suppression before confirming success or durably queue it, and alert on processing failures. Keep GET requests read-only so link scanners cannot accidentally unsubscribe people. A separate body link can show a preference page.
Endpoint Test
Use a disposable subscriber in your own test environment:
curl --include --request POST \
'https://mail.example.com/unsubscribe/TEST_TOKEN' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data 'List-Unsubscribe=One-Click'
The request should produce a successful response without a redirect and suppress the intended subscription. Repeat it to check safe handling of an already-unsubscribed recipient. Inspect the list state and subsequent sending behavior, not only the HTTP status.
RFC 8058 specifies the List-Unsubscribe=One-Click key/value pair. Receivers SHOULD use multipart/form-data and MAY use application/x-www-form-urlencoded, as in the test above. Support both encodings so a working form-encoded test does not hide a failure with another permitted receiver. The RFC does not prescribe a universal HTTP response-time deadline. Respond promptly, monitor failures and meet the receiving provider’s unsubscribe-processing interval. RFC 8058.
Amazon SES Example
The following request illustrates custom headers using the SES v2 API, following AWS’s example. Replace the example identities, recipient and token, configure DKIM, and implement the endpoint and suppression checks separately.
import boto3
ses = boto3.client("sesv2")
ses.send_email(
FromEmailAddress="[email protected]",
Destination={"ToAddresses": ["[email protected]"]},
Content={
"Simple": {
"Subject": {"Data": "Test newsletter", "Charset": "UTF-8"},
"Body": {
"Text": {
"Data": (
"Test newsletter. Unsubscribe: "
"https://mail.example.com/preferences/TEST_TOKEN"
),
"Charset": "UTF-8",
}
},
"Headers": [
{
"Name": "List-Unsubscribe",
"Value": "<https://mail.example.com/unsubscribe/TEST_TOKEN>",
},
{
"Name": "List-Unsubscribe-Post",
"Value": "List-Unsubscribe=One-Click",
},
],
}
},
)
Use the API header field, not message tags. Verify the delivered result, including DKIM coverage. Adding headers does not itself provide a working unsubscribe service.
Common Failures to Check
- Headers added after signing: configure signing so both headers are covered.
- Login, CAPTCHA or confirmation on POST: the automatic request cannot complete that flow.
- GET changes subscription state: scanners can fetch links without a user intending to unsubscribe.
- Token identifies the user but not the list: the request can remove the wrong subscription.
- Application ignores suppression: the endpoint succeeds, but the next campaign still sends.
- Suppression exists in only one platform: a second sender can reintroduce unwanted mail.
Have an owner for the endpoint, suppression records and signing configuration. Retest after changes to any of them. Implementation effort depends on your existing subscription system, so a universal “two hours and no maintenance” estimate is not dependable.
Next Steps
Keep the test evidence with your email configuration runbook. Review SPF, DKIM and DMARC setup and the complete provider requirements alongside unsubscribe testing.
If your team cannot identify which system owns subscriptions or suppression, contact us for an email configuration review.
