> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# One-click unsubscribe (RFC 8058)

> List-Unsubscribe headers for the native unsubscribe button in Gmail and Yahoo.

**RFC 8058** is the inbox “leave” button, no need to open the email and hunt for the footer.

## Why use it?

Gmail and Yahoo require one-click unsubscribe for promotional mail. Without the right headers, opt-out depends only on the HTML link (preference center). With RFC 8058, the mailbox shows a native button and Notifique honors the request immediately.

## When to use it

* **MARKETING** template (and campaigns/automations using it) → RFC 8058 headers **by default**
* **`POST /v1/email/messages`** when the recipient maps to a contact → **by default**
* **Transactional** email (receipt, OTP, password reset) → set `listUnsubscribe: false`
* Recipient has **no contact** in the workspace → headers are not injected (no token)

## How it works

1. On send, Notifique issues a token (same family as `{{preferences_link}}`) and sets MIME headers:
   * `List-Unsubscribe: <https://…/w/list-unsubscribe/:contactId?token=…>`
   * `List-Unsubscribe-Post: List-Unsubscribe=One-Click`
2. Gmail/Yahoo **POST** to that URL with body `List-Unsubscribe=One-Click` (no cookies, no login), opt-out happens **only on POST**.
3. A **GET** to the same URL only validates the token and shows a confirmation page (no preference change, avoids scanners/prefetch).
4. On POST, Notifique unsubscribes **immediately**:
   * with `topic` in the URL (template with a topic) → topic `UNSUBSCRIBED` (invalid topic → error, no global fallback)
   * without topic → `receiveMarketing = false`
5. The success page may link to the preference center to resubscribe.

<Info>
  The footer with `{{preferences_link}}` / “click here to unsubscribe” still exists. RFC 8058 is **additive** (headers); it does not replace the preference center.
</Info>

## Direct API (`POST /v1/email/messages`)

```json theme={null}
{
  "from": "marketing@yourdomain.com",
  "to": ["customer@example.com"],
  "subject": "This week’s updates",
  "html": "<p>Hello!</p>",
  "listUnsubscribe": true,
  "listUnsubscribeTopicId": "cltopic..."
}
```

| Field                    | Default | Effect                                                                               |
| ------------------------ | ------- | ------------------------------------------------------------------------------------ |
| `listUnsubscribe`        | `true`  | Injects headers when the recipient is a **contact** in the workspace                 |
| `listUnsubscribeTopicId` | ,       | Scopes one-click to a [topic](/en/contacts-api/como-funciona/topicos-de-comunicacao) |

If `listUnsubscribeTopicId` does not exist in this workspace: **400** with `code` **`INVALID_LIST_UNSUBSCRIBE_TOPIC`**. See [Error responses](/en/guides/conceitos/resposta-de-erros).

For transactional mail:

```json theme={null}
{
  "listUnsubscribe": false
}
```

## Next steps

* [Communication topics](/en/contacts-api/como-funciona/topicos-de-comunicacao)
* [Email Quick Start](/en/emails-api/como-funciona/quick-start)
* [Template variables](/en/template-api/como-funciona/variaveis-disponiveis-e-crud)