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

> Listmonk enables one-click unsubscribes with RFC 8058 List-Unsubscribe-Post headers. Learn how this feature ensures compliance and improves user experience by default.

- Repository: [Kailash Nadh/listmonk](https://github.com/knadh/listmonk)
- Tags: internals
- Published: 2026-05-19

---

**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`](https://github.com/knadh/listmonk/blob/main/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.

```toml
[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.

```bash
./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`](https://github.com/knadh/listmonk/blob/main/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:

```go
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`](https://github.com/knadh/listmonk/blob/main/cmd/subscribers.go) (lines 74–79), the application constructs the header map for confirmation messages:

```go
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`](https://github.com/knadh/listmonk/blob/main/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`](https://github.com/knadh/listmonk/blob/main/internal/manager/manager.go) for campaign emails and [`cmd/subscribers.go`](https://github.com/knadh/listmonk/blob/main/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`](https://github.com/knadh/listmonk/blob/main/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`](https://github.com/knadh/listmonk/blob/main/internal/manager/manager.go)) and **opt-in confirmation emails** (processed through [`cmd/subscribers.go`](https://github.com/knadh/listmonk/blob/main/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.