# List-Unsubscribe Header Generator > Generate the RFC 8058 one-click unsubscribe header pair, optional RFC 2369 mailto fallback, optional List-ID, line-folding evidence, a receiver POST example, DKIM coverage requirements, endpoint findings, suppression-readiness attestations, and engineering exports. Header syntax is only the signal; the endpoint and suppression system must deliver the outcome. - **Canonical page:** [https://emailbump.com/tools/list-unsubscribe-header-generator](https://emailbump.com/tools/list-unsubscribe-header-generator) - **Interactive tool:** [Open the List-Unsubscribe header generator](https://emailbump.com/tools/list-unsubscribe-header-generator) - **Category:** Subscription operations, deliverability, and message headers - **Standards:** [RFC 8058](https://www.rfc-editor.org/rfc/rfc8058.html), [RFC 2369](https://www.rfc-editor.org/rfc/rfc2369.html) - **Updated:** July 2026 - **Privacy:** Header generation, validation, line accounting, and exports run locally - **Network boundary:** The endpoint is modeled but never contacted ## The central principle One-click unsubscribe is a protocol capability, not an unsubscribe-looking URL. The capability has three connected parts: 1. A `List-Unsubscribe` header containing one personalized HTTPS URI 2. A `List-Unsubscribe-Post` header with the exact value `List-Unsubscribe=One-Click` 3. An endpoint that accepts the receiver's POST and completes suppression without another user action The basic pair looks like: ```text List-Unsubscribe: List-Unsubscribe-Post: List-Unsubscribe=One-Click ``` A sender can add a mailto fallback: ```text List-Unsubscribe: , List-Unsubscribe-Post: List-Unsubscribe=One-Click ``` The mailto URI supports older or alternate RFC 2369 client behavior. It does not replace the RFC 8058 HTTPS POST. ## What the interactive tool accepts The operator supplies: - Message-stream classification - Personalized HTTPS endpoint template - Optional mailto fallback address - Optional mailto subject command - Optional human-readable list name - Optional List-ID value - Header-folding preference - Seven operational attestations The tool preserves merge placeholders such as: ```text {{unsubscribe_token}} %unsubscribe_token% [unsubscribe_token] ``` It substitutes a harmless example token only while parsing the URL and constructing the receiver request preview. The exported header keeps the original template for integration into the sender. ## Generated artifacts The interactive page produces: - Raw CRLF-separated message header block - Exact `List-Unsubscribe` value - Exact `List-Unsubscribe-Post` value - Optional `List-ID` field - Physical-header-line byte ledger - Longest-line measurement - Receiver HTTPS POST example - DKIM signer coverage handoff - Endpoint contract - Token-design guidance - Findings and limitations - Operational-readiness checklist - Plain-text engineering runbook - Structured JSON report The page does not claim an inbox provider will display an unsubscribe control. Mailbox providers can consider message classification, authentication, domain reputation, traffic history, user engagement, and product-specific eligibility in addition to header syntax. ## The List-Unsubscribe field RFC 2369 defines list command header fields that use angle-bracketed URIs. For RFC 8058 one-click behavior, one HTTPS URI must appear in `List-Unsubscribe`. Example: ```text List-Unsubscribe: ``` The HTTPS URI must contain enough information to identify: - The recipient - The subscription list - The intended unsubscribe operation The receiver POST body does not carry the recipient address or list identifier. That state must be available through the URI. ## The List-Unsubscribe-Post field The second field is exact: ```text List-Unsubscribe-Post: List-Unsubscribe=One-Click ``` Changing capitalization of the field name is harmless because message header names are case-insensitive, but the tool uses conventional capitalization. The field value is the single protocol key/value pair defined by RFC 8058. This field distinguishes a user-consented one-click POST action from automated GET requests made by security scanners, link inspectors, or other infrastructure. ## Why GET and POST have different behavior Security systems often fetch URLs found in messages and headers. A GET request can happen without the recipient asking to unsubscribe. Therefore: - GET can display a preferences page or confirmation experience - GET must not automatically suppress solely because the URL was fetched - RFC 8058 POST represents the receiver's user-consented one-click action - POST must complete the intended unsubscribe without an additional confirmation page An endpoint can support both methods on the same personalized URI: - `GET /u/token` shows a manual page - `POST /u/token` performs one-click suppression The two methods must remain intentionally different. ## Receiver POST request For: ```text List-Unsubscribe: ``` the modeled request is: ```http POST /u/opaque-token HTTP/1.1 Host: email.example.com Content-Type: application/x-www-form-urlencoded Content-Length: 26 List-Unsubscribe=One-Click ``` RFC 8058 permits the receiver to use `application/x-www-form-urlencoded` and describes multipart form data as well. The request does not need: - A browser login - A session cookie - An HTTP Authorization header - A CSRF token tied to a web session - A recipient form - A list-selection form - A confirmation click The unsubscribe URI itself must carry validated authority for the narrow action. ## Redirect behavior RFC 8058 says the sender must not return an HTTPS redirect for the one-click POST. Redirected POST behavior has historically been unreliable, and some clients transform a redirected POST into GET. The endpoint should terminate directly at the personalized URI. Infrastructure reviews should check for redirects introduced by: - HTTP-to-HTTPS middleware - Bare-domain to `www` canonicalization - Region routing - Language routing - Authentication middleware - CDN configuration - Trailing-slash normalization - Legacy campaign domains - Link-branding domains - Provider migrations A 301, 302, 303, 307, or 308 response is not a substitute for a direct handler at the URI placed in the delivered message. ## Token design The URI should include an opaque or otherwise hard-to-forge value. A strong token binds the narrow unsubscribe action to: - Tenant or account - Recipient identity - List or subscription identity - Token version - Allowed action - Optional issuance context Two common designs are: ### Random reference token The URI carries a sufficiently random database key. ```text https://email.example.com/u/7qM2...opaque... ``` The server loads a narrow unsubscribe record and applies it idempotently. ### Signed stateless token The URI carries encoded claims plus a message authentication code or signature. The handler: 1. Parses the token 2. Verifies the signature 3. Checks the token version and intended action 4. Resolves the tenant, recipient, and list 5. Writes suppression idempotently A signed token is not the same as encrypted data. If the token contains a raw email address, that address can still be exposed in: - Message headers - Provider logs - Proxy logs - Browser history after manual GET - Security tools - Forwarded messages - Support tickets - Screenshots Prefer an opaque representation that does not disclose the mailbox. ## Token expiration An unsubscribe token should remain usable for the reasonable lifetime of the message. A recipient can act on an older campaign long after a short authentication-session TTL. If tokens expire too quickly: - Old messages show a one-click capability that no longer works - Recipients may report mail as spam instead - Provider tests can fail - Suppression becomes inconsistent across campaigns Token lifetime is an operational policy choice. Design it for unsubscribe semantics, not by copying a password-reset expiration. ## Idempotency and replay The same valid URI can be posted more than once. An idempotent handler: - Leaves an already-unsubscribed record unsubscribed - Returns a successful terminal response - Does not recreate consent - Does not suppress a different list - Does not fail destructively on duplicate events - Preserves an auditable first and latest request time where useful Replay safety matters because mailbox providers, recipients, test systems, retries, or operators can repeat the request. ## Scope One-click does not inherently mean “unsubscribe this person from every message sent by the company.” The URI should map to the subscription represented by the message. Depending on the product, that can be: - Weekly newsletter - Product announcements - Promotional offers - Event reminders - Community digest - Research updates Required account, receipt, security, or contractual notices need separate stream design. A token that globally suppresses every message can create account-safety or legal problems; a token that suppresses only one campaign execution is too narrow. ## Mailto fallback RFC 2369 encourages mailto support as an alternate command mechanism. Example: ```text ``` The generator: - Validates one mailbox - Percent-encodes the subject value - Places the mailto URI after HTTPS - Folds only between alternate URIs when requested The mailto handler still needs production logic. It should: - Identify the intended recipient and list safely - Handle replies, forwarding, and aliases - Avoid trusting a spoofable From address as the only authorization - Apply suppression idempotently - Return useful operational evidence Mailto does not meet RFC 8058 one-click by itself because it does not provide the defined HTTPS POST action. ## List-ID The optional `List-ID` field gives the list a stable identifier. Example: ```text List-ID: Product updates ``` The interactive tool accepts: - Human-readable list name - DNS-style list identifier The identifier should remain stable across ordinary campaign changes. It describes the subscription stream rather than one campaign or subject line. List-ID can help: - Mailbox software group list traffic - Operators distinguish subscription streams - Support teams identify the source list - Subscription management features map messages - Forensic review compare campaigns It is not a replacement for one-click headers, visible controls, consent evidence, or an internal list primary key. ## Header folding Internet message fields have physical-line limits and line-length recommendations. The generator can fold a List-Unsubscribe field between alternate URIs: ```text List-Unsubscribe: , ``` The continuation line begins with whitespace. The tool never inserts folding whitespace inside angle brackets. RFC 2369 says MTAs must not insert whitespace within the bracketed URI. This is unsafe: ```text List-Unsubscribe: ``` The URI can be corrupted or interpreted inconsistently. If one personalized URI is too long to fit safely on a physical line, shorten the route or token. Folding cannot repair an oversized single URI. ## Physical-line evidence The tool: - Joins generated fields with CRLF - Splits the block into physical lines - Measures every line in UTF-8 bytes - Reports the longest line - Blocks a physical line above 998 bytes - Notes lines above the 78-character recommendation Personalized HTTPS URIs commonly make a line longer than 78 characters. The important implementation boundaries are to remain within the hard limit, preserve URI integrity, and test the final delivered artifact after provider rewriting. ## Header injection defense Every text input is checked for carriage return or line feed. If a value contains CR or LF, the generator produces a blocking finding. This prevents an input such as a list name or URL from silently creating: - A second message field - A malformed continuation - An injected recipient field - Conflicting unsubscribe fields - A broken DKIM signature surface Production senders must apply equivalent validation at the point where untrusted or tenant-controlled data enters message headers. ## DKIM coverage RFC 8058 requires a valid DKIM signature that covers: - `List-Unsubscribe` - `List-Unsubscribe-Post` Both field names must be represented in the DKIM `h=` signed-header list. Conceptual signer coverage: ```text h=...:list-unsubscribe:list-unsubscribe-post; ``` The tool does not generate a DKIM-Signature field. A valid signature also depends on: - Signing domain - Selector - Private key - Canonicalization - Body hash - Header order - Duplicate header behavior - Timestamp and optional expiration - Published public key - Final message bytes The correct pipeline is: 1. Personalize the HTTPS URI 2. Assemble the final unsubscribe fields 3. Assemble the final message 4. DKIM-sign the final fields 5. Avoid downstream rewriting 6. Send the message 7. Inspect the delivered raw headers 8. Verify DKIM passes and `h=` covers both fields Adding List-Unsubscribe after signing does not satisfy this requirement. ## Duplicate fields RFC 8058 describes one List-Unsubscribe field and one List-Unsubscribe-Post field. Avoid a pipeline where: - The application adds one pair - An email service adds another pair - A downstream relay rewrites only one field - DKIM signs one copy but not the effective copy Determine which system owns header generation. Disable duplicate insertion where possible and inspect delivered messages from every send path. ## Visible body control Header-based one-click should not be the only recipient-facing unsubscribe mechanism. The message body should contain a clear, accessible unsubscribe link. That link can lead to: - Direct manual unsubscribe - A preference center - Topic controls - Frequency controls - Pause options The visible link does not need to behave like the automated receiver POST. A preference page can be appropriate for a person while the RFC 8058 POST remains a direct machine action. Do not hide the body control through: - Extremely low contrast - Tiny type - Ambiguous copy - An unrelated settings path - Mandatory login - Multiple confirmation screens ## Subscription and transactional streams The interactive tool asks for a stream classification because unsubscribe scope is not merely syntax. ### Subscription Examples: - Newsletters - Promotions - Product announcements - Recipient-controlled digests These are the natural one-click use case. ### Transactional Examples: - Password resets - Receipts - Security alerts - Reservation confirmations Provider bulk-sender one-click requirements generally focus on marketing or subscription traffic. Adding a control that globally suppresses required account mail can be harmful. Some transactional streams can still benefit from specific preference controls, but the scope needs deliberate design. ### Mixed A message that combines required account content and promotion is harder for: - Recipients to understand - Providers to classify - Operators to suppress - Legal teams to assess - Support teams to explain Separating required and promotional streams usually creates clearer identity, consent, suppression, and authentication behavior. ## Suppression pipeline The one-click endpoint is the entrance to a distributed operational change. ### Receive Accept the HTTPS POST at the exact delivered URI without redirect, browser state, or interactive confirmation. ### Validate Verify the opaque token and bind it to the intended tenant, recipient, list, and action. ### Persist Write an idempotent suppression or consent-state event with an auditable timestamp and source. ### Propagate Update: - Primary contact state - List membership - Derived segments - Campaign eligibility caches - Scheduled jobs - Provider-held audiences - Data warehouse or reverse ETL paths - Replicas - Retry queues - Automation enrollment ### Stop queued mail A database flag does not help if campaign payloads are already materialized in a queue. The send worker should perform a final suppression check close to delivery. ### Verify Confirm that the recipient is absent from subsequent subscription sends across every campaign and automation path. ## Seven readiness attestations The generator records explicit human evidence. ### POST support The endpoint accepts `List-Unsubscribe=One-Click` and completes suppression. ### No redirect The exact delivered URI has a direct terminal handler. ### Opaque token The token is hard to forge, validated, and does not expose raw recipient identity. ### Idempotent replay Repeated valid requests preserve the correct suppressed state. ### Suppression propagation Queues, segments, replicas, and vendors stop future list mail promptly. ### DKIM coverage A valid delivered DKIM signature covers both unsubscribe headers. ### Visible body link The message includes a clear recipient-facing unsubscribe control. These checks are operator attestations. The browser cannot infer them from a URL template. ## Findings generated by the tool The implementation review can report: - Missing HTTPS endpoint - Non-HTTPS scheme - URI user information - URI fragment - Missing personalization placeholder - Apparent raw email exposure - Excessively long URI - Invalid mailto address - Invalid List-ID fields - Physical header line above 998 bytes - Physical line above the 78-character recommendation - Transactional-stream scope note - Mixed-purpose classification warning - Missing mailto fallback - Missing List-ID - Incomplete operational evidence - CR/LF header injection attempt “Header syntax is coherent” does not mean: - The placeholder is replaced - The endpoint exists - The endpoint accepts POST - The endpoint avoids redirects - The token is secure - Suppression propagates - DKIM covers the fields - An inbox provider will show UI - The message meets every provider or legal requirement ## Testing workflow ### 1. Generate the template Build the header pair with the real merge-tag syntax used by the sending system. ### 2. Send to a controlled recipient Use the same application, provider, relay, and campaign path as production. ### 3. Inspect raw delivered headers Confirm: - Exactly one List-Unsubscribe field - Exactly one List-Unsubscribe-Post field - Personalized HTTPS URI - Optional mailto encoding - Optional stable List-ID - No illegal folding inside URIs ### 4. Verify DKIM Confirm a valid signature covers both unsubscribe field names. ### 5. Test GET separately Fetching the URL as GET must not accidentally suppress due to scanner-style prefetch. ### 6. Test POST without context Send: ```text List-Unsubscribe=One-Click ``` without login cookies or HTTP authorization. Confirm a direct terminal response. ### 7. Replay POST the same valid URI again. Confirm the outcome remains safely unsubscribed. ### 8. Test tampering Change token bytes, list identifiers, or tenant context. Confirm the endpoint refuses unauthorized mutations without revealing sensitive state. ### 9. Inspect propagation Verify contact state, list state, segments, queues, providers, automations, and scheduled campaigns. ### 10. Observe future traffic Ensure no further subscription mail is delivered for the suppressed list. ## JSON report The downloadable report includes: - Generation timestamp - Method boundary - Message classification - HTTPS URL template - Mailto configuration - List-ID configuration - Folding setting - Raw header block - Receiver request example - Every physical line and byte count - Longest-line measurement - Required DKIM coverage names - Findings - Readiness attestations An agent can use the report as an implementation brief, but should not make a production DNS, sender, or suppression change without live message evidence and the required authority. ## Common questions ### Does mailto satisfy one-click requirements? No. It is an optional alternate RFC 2369 URI. RFC 8058 one-click requires HTTPS and the List-Unsubscribe-Post field. ### Can the HTTPS URI open a preferences page? It can offer a manual GET experience, but the receiver POST must complete the unsubscribe without another action. ### Can POST redirect to the real endpoint? RFC 8058 says the sender must not return an HTTPS redirect for the one-click POST. ### Should the URL contain an email address? Prefer an opaque, hard-to-forge token. Raw addresses expose identity and are easier to manipulate. ### Can the handler require login? No. Receiver POST does not carry the recipient's web session. ### Can the handler require CSRF state? It cannot rely on browser-session CSRF state. The validated opaque URI authorizes the narrow unsubscribe action. ### Does one-click mean global unsubscribe? Not automatically. Scope the token to the subscription represented by the message. ### Does adding the fields guarantee inbox UI? No. Providers can apply additional authentication, reputation, classification, and eligibility criteria. ### Is a visible body link still needed? Yes. Header-based one-click and a clear recipient-facing body control serve different interaction paths. ### Must transactional messages include one-click? Provider requirements generally target marketing or subscription messages. Required account streams need contextual product, provider, and legal review. ### What should the endpoint return? It should return a direct successful terminal response after processing a valid request, without redirect or interactive confirmation. Exact status and response-body conventions should be tested with the sender's target receivers and provider guidance. ### How quickly should suppression propagate? Promptly enough to stop future list mail, including materialized queues and connected vendors. Gmail and Yahoo sender guidance has used a two-day outer expectation for relevant bulk traffic, while well-designed systems usually update much faster. ## Primary sources - [RFC 8058 — Signaling One-Click Functionality for List Email Headers](https://www.rfc-editor.org/rfc/rfc8058.html) - [RFC 2369 — URLs as Meta-Syntax for Core Mail List Commands](https://www.rfc-editor.org/rfc/rfc2369.html) - [Gmail email sender guidelines](https://support.google.com/mail/answer/81126) - [Yahoo Sender Hub subscription guidance](https://senders.yahooinc.com/subhub/) ## Related tools and guidance - [Email header analyzer](https://emailbump.com/tools/email-header-analyzer.md) - [DKIM record checker](https://emailbump.com/tools/dkim-record-checker.md) - [CAN-SPAM readiness checker](https://emailbump.com/tools/can-spam-readiness-checker.md) - [DMARC record builder](https://emailbump.com/tools/dmarc-record-builder.md) - [One-click unsubscribe glossary definition](https://emailbump.com/glossary/one-click-unsubscribe.md) - [Suppression list glossary definition](https://emailbump.com/glossary/suppression-list.md) - [Spam complaint glossary definition](https://emailbump.com/glossary/spam-complaint.md) - [Transactional versus marketing email](https://emailbump.com/blog/transactional-vs-marketing-email.md) - [Reducing spam complaints](https://emailbump.com/blog/reduce-transactional-email-spam-complaints.md) - [Deliverability documentation](https://emailbump.com/docs/deliverability.md)