Should I include List-Unsubscribe headers in transactional emails and what are the DKIM best practices?
Updated on 6 Sep 2026: We clarified which transactional messages need one-click unsubscribe and added current DKIM implementation guidance.
Do not add List-Unsubscribe to every message labeled transactional. Gmail and Yahoo exclude true transactional mail, such as requested password resets, one-time passwords, receipts, and security alerts, from their one-click requirements. Include the headers in marketing and subscription mail, including recurring notifications, trial reminders, product digests, optional alerts, and other messages the recipient can reasonably stop.
For DKIM, use RSA-SHA256, sign the headers that define the message, avoid the body length tag, use strong keys, rotate selectors safely, and sign List-Unsubscribe and List-Unsubscribe-Post when one-click unsubscribe is enabled. The only mandatory DKIM signed header is From, but signing only From leaves too much important message context unsigned.
- Use List-Unsubscribe on marketing, product digests, subscribed notifications, account invites, trial reminders, and other messages a recipient can reasonably stop.
- Keep password resets, one-time passwords, security notices, fraud alerts, receipts, and required account mail outside normal unsubscribe suppression.
- For one-click unsubscribe, publish both List-Unsubscribe and List-Unsubscribe-Post, then cover both headers with DKIM.
- Use RSA-SHA256 with 2048-bit DKIM keys where supported, keep selectors separate by stream, and avoid the DKIM body length tag.
When List-Unsubscribe belongs in transactional email
List-Unsubscribe belongs in email described internally as transactional when the message is really a subscription the recipient can stop. Gmail treats some notification messages as subscription mail, while messages caused by an explicit user action or request remain non-subscription mail.
The common trap is assuming "transactional" means "unsubscribe does not apply". A password reset requested by the account holder is different from a recurring product invite. An order receipt is different from a daily digest. A security alert is different from a trial reminder. Classify each stream by why the recipient receives it and whether the recipient can stop it.
The default policy is simple: if a recipient can report the message as spam instead of completing the action, give them a clean opt-out path. A complaint is worse for reputation than an unsubscribe request.
|
|
|
|---|---|---|
Newsletter | Yes | Stop newsletter |
Product digest | Yes | Stop digests |
Recurring account invite | Yes | Suppress invites |
Opt-in follow-up | Yes | Suppress follow-ups |
Trial reminder | Yes | Stop reminders |
Required legal notice | Usually no | Keep required |
Password reset | Usually no | Keep critical |
Security alert | Usually no | Keep critical |
Receipt | Usually no | Keep record |
Practical treatment by message type
Google requires one-click unsubscribe for marketing and subscription messages sent by domains delivering more than 5,000 messages a day to personal Gmail accounts. Some recurring notifications count as subscription mail, but requested password resets, purchase receipts, and one-time passwords do not. Yahoo's requirement applies to promotional and marketing messages, not true transactional messages. The Google guidance makes the threshold and message distinction important for daily operations.
List-Unsubscribe decision infographic for optional alerts, invites, digests, and critical mail.
Keep a visible body unsubscribe link
List-Unsubscribe headers create a machine-readable route for mailbox controls. They do not replace the visible unsubscribe link in the message body. Gmail requires affected bulk marketing and subscription messages to support one-click unsubscribe and include a clear body link.
- Make the body link easy to find and readable on mobile devices.
- The body link can open a preference center; it does not need to perform the RFC 8058 POST action.
- Keep the category shown in the preference center consistent with the list encoded in the one-click URL.
- Test the header action and the body link separately because they use different request paths.
A valid header does not guarantee that an inbox will show its native unsubscribe control. The mailbox provider decides whether to display it based on implementation checks and sender eligibility, so the body link remains necessary.
What the unsubscribe action should do
Before adding List-Unsubscribe to transactional email, decide what the request changes. The header is not only a technical marker. It creates a user action that your systems need to honor predictably.
Map each one-click request to the subscription list or message category identified by the opaque URL token. Do not silently suppress unrelated subscriptions unless the recipient chose a global opt-out or your published policy clearly defines that result. Never let a category unsubscribe suppress password resets, one-time passwords, security alerts, fraud notices, required legal notices, or receipts.
Weak policy
- Every unsubscribe either blocks everything or does nothing useful.
- Support teams cannot explain why a user stopped receiving specific notifications.
- Critical mail gets blocked or unwanted mail keeps generating complaints.
Better policy
- Each token maps to one named list or notification category.
- The app shows which notification categories are suppressed for the user.
- Unwanted mail stops while account-critical mail continues.
A useful transactional unsubscribe flow also needs a "this is not me" path. This matters when someone enters the wrong address, typo-subscribes another person, or uses an address they do not control. In that case, the recipient does not want to manage preferences. They want your system to stop treating the address as theirs.
Suppression decision modeltext
Unsubscribe from a marketing email: suppress the list identified by the token offer a separate global marketing opt-out Unsubscribe from a digest or notification email: suppress that notification class leave unrelated subscriptions unchanged keep password resets and security alerts Unsubscribe from an invite or opt-in follow-up: suppress future messages from the same source mark the address for review or re-confirmation This is not me: invalidate the pending relationship suppress follow-up reminders preserve account security notices where required
This policy also protects deliverability. Recipients who cannot stop unwanted account-adjacent mail use the spam button. That complaint damages sender reputation more than a properly handled unsubscribe. For teams using shared IPs, the effect can spill across streams because marketing and transactional traffic share reputation signals even when the content types are different.
How to format List-Unsubscribe and one-click headers
The modern pattern is to include List-Unsubscribe and, for one-click unsubscribe, List-Unsubscribe-Post. The HTTPS URL must accept an RFC 8058 POST without login, cookies, redirects, or another confirmation step. A manual browser GET to the same URL can show a confirmation page or preference center. A mailto option remains a fallback, but it does not satisfy Gmail's one-click requirement.
One-click List-Unsubscribe header exampletext
List-Unsubscribe: <https://example.com/u/abc123>, <mailto:unsubscribe@example.com?subject=unsubscribe> List-Unsubscribe-Post: List-Unsubscribe=One-Click
Expected one-click POST bodytext
POST /u/abc123 HTTP/1.1 Host: example.com Content-Type: application/x-www-form-urlencoded Content-Length: 26 List-Unsubscribe=One-Click
If you use one-click unsubscribe, sign both headers with DKIM. RFC 8058 requires List-Unsubscribe and List-Unsubscribe-Post to appear in the h= list of a valid DKIM signature. Without that coverage, a receiver should not offer the one-click action.
Do not add a List-Unsubscribe header until the endpoint and suppression rules are ready. A broken endpoint trains mailbox providers and users that your unsubscribe process cannot be trusted.
- Use a durable HTTPS URL with a recipient-specific, opaque, hard-to-forge token and no exposed personal data.
- Make repeated POST requests idempotent so retries return success without changing unrelated preferences.
- Treat GET as a manual navigation request, not the one-click action, to avoid opt-outs caused by link scanners.
- Route mailto fallback requests into an automated processor instead of a shared mailbox.
- Honor the identified list or category within 48 hours and keep a durable audit event.
DKIM headers worth signing
There is no universal mailbox-provider list of DKIM headers that earns special placement by itself. DKIM proves that selected headers and the message body were signed by a domain. The best list is the set of stable headers that identify the message and should not be inserted, removed, or modified in transit.
Start with From, To, Subject, Date, Message-ID, Reply-To, Sender, MIME-Version, Content-Type, List-ID, List-Unsubscribe, and List-Unsubscribe-Post when present. For threaded mail, also consider In-Reply-To and References. Sign Cc when it exists and is stable. Do not depend on Bcc in delivered mail because Bcc should normally be removed before delivery.
Practical DKIM h= listtext
h=From:To:Subject:Date:Message-ID:Reply-To:Sender: MIME-Version:Content-Type:List-ID:List-Unsubscribe: List-Unsubscribe-Post
Oversigning adds an absent instance of a header name to h=, or lists an existing single-instance header twice, so a later system cannot add another copy without breaking the signature. Use it selectively for headers that should appear once, such as From, Subject, Date, Message-ID, Sender, Reply-To, List-Unsubscribe, and List-Unsubscribe-Post. Do not oversign headers that legitimate forwarding or list processing is expected to add.
Oversigning patterntext
h=From:From:Subject:Subject:Date:Date:Message-ID:Message-ID: List-Unsubscribe:List-Unsubscribe:List-Unsubscribe-Post: List-Unsubscribe-Post
Use a DKIM validation pass after every mail pipeline change. Suped's DKIM checker helps verify selectors, public keys, and DNS syntax before you diagnose deeper delivery behavior.
|
|
|
|---|---|---|
From | Always | Required by DKIM |
Subject | Yes | Visible content |
Date | Yes | Message age |
Message-ID | Yes | Message identity |
List-ID | When present | Subscription identity |
List-Unsubscribe | Yes | One-click trust |
Reply-To | Usually | Reply path |
Received | No | Changes in transit |
DKIM header signing choices
DKIM parameters and replay controls
DKIM header choices matter, but DKIM parameters can create or remove real risk. Pay close attention to the signing algorithm, body length tag, signature expiration, key length, canonicalization, and selector design.
- Sign with rsa-sha256. RFC 8301 prohibits rsa-sha1 for DKIM signing and verification.
- Avoid the l= tag unless you have a narrow, well-tested reason. It lets unsigned body content be appended after the signed portion.
- Use the x= tag carefully. Expiration can limit replay time, but it does not prevent replay before expiry, and a window that is too short breaks delayed delivery.
- Prefer relaxed header and body canonicalization unless a specific sender requires simple canonicalization.
- Use RSA keys of at least 1024 bits and prefer 2048 bits. If a DNS interface requires it, split a long public key into adjacent quoted strings within one TXT record, not multiple records.
- Use different selectors for each platform or stream. Publish the replacement key, switch signing to the new selector, retain the old public key for delayed mail, then retire it.
DKIM signature fields to inspecttext
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=example.com; s=selector1; t=1730755896; x=1730842296; h=From:To:Subject:Date:Message-ID:List-Unsubscribe; bh=...; b=...
DKIM replay is not solved by one setting. Stronger controls come from signatures tied to the visible From domain, a measured validity window, limited abuse exposure, complaint monitoring, fast key rotation, and DMARC policy enforcement. Suped's DMARC monitoring ties authentication results to sources, policies, and issues that need action.
DMARC record detail view showing SPF, DKIM, DMARC, rDNS diagnostics, and DNS records
That workflow matters because DKIM does not stand alone. DMARC checks whether a passing SPF or DKIM identity matches the visible From domain. A valid DKIM signature for an unrelated domain does not support DMARC for the From domain. If mixed streams share IPs, source-level visibility becomes more important because one stream's complaints can affect another stream's placement.
Mixed IPs and mixed message types
Sending marketing and transactional mail from the same handful of IPs is workable, but it makes classification and reputation management less forgiving. If a shared IP sends account confirmations, newsletters, product alerts, trial reminders, and promotional campaigns, mailbox providers see one technical source with several user experiences.
The immediate fix is not adding List-Unsubscribe everywhere. Separate streams logically, keep From domains and DKIM selectors consistent by stream, and give each stream the right unsubscribe behavior. For Gmail subscription messages, use a human-readable List-ID header or a unique From address for each subscription list. Mixed IPs need stricter hygiene because complaints, bounces, and authentication failures are less isolated.
Email stream routing flowchart for marketing, optional alerts, and critical transactional mail.
- Give marketing, transactional, and product notification platforms their own DKIM selectors.
- Assign each subscription stream a List-ID or unique From address and map it to one suppression category.
- Keep complaint, bounce, unsubscribe, and DMARC failure reporting tied to message class.
- Do not let one generic sender identity cover both required account mail and promotional mail.
- Use Suped's domain health workflow to check DMARC, SPF, and DKIM signals together.
?
What's your domain score?
Deep-scan SPF, DKIM & DMARC records for email deliverability and security issues.
For teams running many domains or client domains, Suped's product brings DMARC monitoring, SPF and DKIM visibility, hosted SPF, hosted DMARC, hosted MTA-STS, blocklist monitoring (blacklist monitoring), real-time alerts, and issue remediation into one workflow. That matters when the question moves from "does this record validate" to "which sender broke authentication and what should change next".
Provider screens that shape implementation
Different sending platforms expose List-Unsubscribe controls in different places. Some generate the headers automatically for marketing sends but leave transactional sends to API settings or custom headers. Document the policy first, then audit every stream that sends as the domain.
Salesforce Marketing Cloud settings for List-Unsubscribe and one-click header controls.
The exact screen will vary by account and sending product, so treat screenshots as implementation prompts, not proof that the whole domain is configured. The source of truth is the final message received by mailbox providers: headers, DKIM signature, domain matching, and the response from the unsubscribe endpoint.
Audit the delivered message after every setting change. Check the final List-Unsubscribe value, the List-Unsubscribe-Post value, the DKIM h= list, the signing domain, the List-ID when used, and the endpoint response before assuming one-click unsubscribe is ready.
Legal and compliance caveats
Treat this as deliverability guidance, not legal advice. The technical recommendation and the legal requirement are related, but they are not the same thing. The right policy depends on where recipients live, what the message says, why it was sent, and whether the email includes commercial content.
- In the United States, CAN-SPAM uses primary purpose. A receipt or security notice does not become marketing because it contains a preference link.
- In Canada, review commercial electronic messages more strictly and keep required account mail separate from optional mail.
- In Europe and the UK, consent, legitimate interest, contract necessity, and local marketing rules need counsel review.
- For global systems, build preference categories flexible enough for regional rules and product-level controls.
Do not let an unsubscribe action stop password resets, one-time codes, security alerts, required legal notices, receipts, or invoices. If the message contains promotional content, remove that content or handle the message as subscription mail.
Implementation checklist
Implement this in a short sequence. Start with classification, then endpoint behavior, DKIM signing, and monitoring. That order avoids the common failure where a team adds headers first and discovers later that no one knows which messages should stop.
- Classify every stream: separate marketing, subscriptions, account lifecycle, receipts, password resets, and security mail.
- Define suppression: map every one-click token to a specific list or category before publishing headers.
- Separate identity: use a List-ID or unique From address for each subscription list, and use different addresses for subscription and non-subscription mail.
- Build endpoint behavior: process POST without login, redirects, or cookies; keep GET harmless until the recipient confirms; and automate any mailto fallback.
- Confirm one-click syntax: use List-Unsubscribe=One-Click in List-Unsubscribe-Post and include one HTTPS URL in List-Unsubscribe.
- Keep a visible link: include an easy-to-find body unsubscribe link on affected marketing and subscription messages.
- Sign unsubscribe headers: include List-Unsubscribe and List-Unsubscribe-Post in the DKIM h= list when present.
- Use current DKIM crypto: sign with RSA-SHA256, prefer 2048-bit keys, avoid l=, and test any x= window against delayed delivery.
- Rotate safely: publish the replacement selector before switching and retain the previous key while signed mail remains in transit.
- Validate real mail: inspect delivered headers, test POST and GET separately, and confirm DKIM after relevant forwarding paths.
- Watch authentication: review DMARC aggregate data for each stream and fix sources whose identifiers do not match the From domain before enforcement.
The most damaging setup is a visible unsubscribe header that points to an endpoint that fails, asks the user to log in, or suppresses the wrong class of mail. That setup increases friction without reducing complaints.
Suped fits this workflow when the team needs a central place to see which sources pass DKIM, which domains meet DMARC requirements, which senders need SPF work, and which issues need immediate action. Hosted SPF and hosted DMARC help when DNS ownership slows down fixes, and real-time alerts help catch authentication breaks before they turn into placement problems.
Views from the trenches
Best practices
Define unsubscribe outcomes for each mail class before publishing one-click headers.
Sign List-Unsubscribe and List-Unsubscribe-Post whenever one-click flow is enabled.
Keep account-critical mail separate from optional notifications and marketing streams.
Common pitfalls
Treating all transactional mail as exempt leaves recipients with only the spam button.
Adding headers before endpoint readiness creates broken opt-out paths for receivers.
Using one shared DKIM selector makes source isolation and emergency rotation slower.
Expert tips
Use tiered suppression so marketing stops while security and access mail continue.
Add a clear not-me path for mistaken account creations and repeated typo-driven signups.
Avoid the DKIM body length tag because later appended content can stay unsigned.
Marketer from Email Geeks says any message a recipient can report as spam should give them a lower-friction way to opt out.
2024-11-04 - Email Geeks
Expert from Email Geeks says one-click unsubscribe headers need to be DKIM signed so receivers can trust the unsubscribe destination.
2024-11-04 - Email Geeks
Practical recommendation
Include List-Unsubscribe when an email stream is marketing or subscription mail, even if your application labels recurring notifications or product digests as transactional. Do not add it to true transactional messages sent because of an explicit user action or legal need. Keep each suppression rule list-specific, show preferences inside the product where useful, and retain an audit trail.
For DKIM, sign more than From. Use RSA-SHA256, sign the stable headers that define the message, cover one-click unsubscribe headers, oversign selected single-instance headers, avoid the body length tag, prefer 2048-bit RSA keys, rotate selectors safely, and monitor DMARC identifier matching.
Suped's product keeps those checks in one workflow: authentication results, alerts, hosted DNS records, source-level diagnostics, and practical remediation steps.
