How Listmonk Implements List-Unsubscribe-Post Headers for RFC 8058 Compliance

Listmonk automatically injects RFC 8058 compliant List-Unsubscribe-Post headers into outbound emails when the unsub_header configuration option is enabled, enabling true one-click unsubscribe functionality in supported email clients.

Listmonk, the high-performance open-source newsletter and mailing list manager, implements the List-Unsubscribe-Post header to ensure recipients can opt out of communications with a single click. This feature adheres to the RFC 8058 standard for one-click unsubscribe mechanisms and applies to both campaign broadcasts and opt-in confirmation emails. By examining the listmonk source code, we can trace exactly how these headers are constructed and attached to outgoing messages.

Configuring the Unsubscribe Header Feature

The generation of List-Unsubscribe headers is controlled by a boolean configuration parameter that determines whether the application includes these headers in all outgoing email traffic.

Configuration File Settings

In the config.toml file, the unsub_header setting under the server section controls this behavior. By default, this value is set to true, meaning headers are automatically added unless explicitly disabled.

[server]

# ... other settings ...

unsub_header = true   # default: true

Command Line Override

Administrators can also control this feature at runtime using the --unsub-header CLI flag when starting the listmonk server. This allows for temporary toggling of the feature without modifying configuration files.

./listmonk --unsub-header=false

Campaign Email Header Injection

When processing campaign deliveries, listmonk constructs email headers within the core manager logic. In internal/manager/manager.go (lines 505–509), the application checks the configuration flag and injects the required headers into the MIME header map.

The code creates a textproto.MIMEHeader and sets two critical headers:

h.Set("List-Unsubscribe-Post", "List-Unsubscribe=One-Click")
h.Set("List-Unsubscribe", "<" + msg.unsubURL + ">")

The msg.unsubURL field contains a cryptographically signed URL pointing to the listmonk unsubscribe endpoint (/api/subscribers/unsubscribe/{list_id}/{subscriber_uuid}). This URL is generated when the message is queued and uniquely identifies both the subscriber and the specific mailing list. The headers are then assigned to out.Headers = h before the messenger (SMTP, SES, or other configured providers) transmits the message.

Opt-in Confirmation Header Injection

Listmonk applies the same unsubscribe header logic to opt-in confirmation emails sent during the subscriber creation process. In cmd/subscribers.go (lines 74–79), the application constructs the header map for confirmation messages:

hdr.Set("List-Unsubscribe-Post", "List-Unsubscribe=One-Click")
hdr.Set("List-Unsubscribe", "<" + unsubURL + ">")

Here, the unsubURL is constructed using the server's public URL configuration (settings.UnsubscribeURL) combined with the subscriber's UUID. This ensures that even subscribers who have not yet confirmed their opt-in status can easily unsubscribe without navigating through additional confirmation steps.

Understanding the One-Click Mechanism

The List-Unsubscribe-Post header implements the RFC 8058 standard by signaling to modern email clients that the unsubscribe action can be performed via an HTTP POST request. The header value List-Unsubscribe=One-Click instructs compliant clients (such as Gmail or Outlook) to present users with a native "Unsubscribe" button that submits a POST request to the URL specified in the List-Unsubscribe header.

While the header suggests a POST operation, listmonk's unsubscribe endpoint (/api/subscribers/unsubscribe/{list_id}/{subscriber_uuid}) actually accepts GET requests. This design satisfies both the RFC requirements and practical implementation constraints, as the endpoint internally performs the unsubscribe action immediately upon access, effectively providing one-click functionality while maintaining compatibility with various email client behaviors.

Disabling List-Unsubscribe Headers

To disable the automatic addition of unsubscribe headers across all email types, set unsub_header = false in config.toml or launch the server with --unsub-header=false. When disabled, listmonk omits all List-Unsubscribe* headers from outgoing messages, forcing recipients to rely solely on the unsubscribe links embedded within the email body content.

Summary

• Listmonk supports RFC 8058 one-click unsubscribe via the List-Unsubscribe-Post header when the unsub_header configuration option is enabled.
• The headers are injected in internal/manager/manager.go for campaign emails and cmd/subscribers.go for opt-in confirmations.
• The List-Unsubscribe header contains a signed URL targeting /api/subscribers/unsubscribe/{list_id}/{subscriber_uuid}.
• The feature is enabled by default but can be disabled via configuration file or CLI flags.
• While the header specifies POST semantics per RFC 8058, listmonk's endpoint uses GET requests to process unsubscribes immediately.

Frequently Asked Questions

What is the List-Unsubscribe-Post header and why does listmonk use it?

The List-Unsubscribe-Post header is an RFC 8058 standard header that enables one-click unsubscribe functionality in modern email clients. Listmonk uses this header to provide recipients with a frictionless opt-out experience directly within their email client's interface, improving deliverability rates and ensuring compliance with emerging email sender requirements from providers like Gmail and Yahoo.

How do I disable List-Unsubscribe headers in listmonk?

Set unsub_header = false in your config.toml file under the [server] section, or start the listmonk server with the --unsub-header=false command line flag. When disabled, the application will not include List-Unsubscribe or List-Unsubscribe-Post headers in any outgoing emails.

Which listmonk email types include the List-Unsubscribe-Post header?

Listmonk adds these headers to both campaign broadcast emails (processed through internal/manager/manager.go) and opt-in confirmation emails (processed through cmd/subscribers.go). This ensures consistent unsubscribe accessibility regardless of whether the recipient is receiving marketing campaigns or initial subscription confirmations.

Is the listmonk unsubscribe endpoint compliant with RFC 8058?

Yes, listmonk implements RFC 8058 by including the required List-Unsubscribe-Post: List-Unsubscribe=One-Click header. While the specification recommends that compliant clients send a POST request to the unsubscribe URL, listmonk's endpoint accepts GET requests and immediately processes the unsubscribe action, effectively satisfying the one-click requirement while maintaining implementation simplicity.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}