# Unsubscribe links and one-click unsubscribe

> What {{unsubscribeLink}}, {{subscriptionManagementLink}} and the List-Unsubscribe header do in Internal and External mode, the subscription preferences page, and the RFC 8058 one-click endpoint POST /api/v0/unsubscribe/oneclick/{payload}.

Releva puts unsubscribe links into every message it sends, so you do not have to build them. This page explains where each link goes, and documents the endpoints behind them for when you test or debug them.

## When to use it

Read it when you design email templates, test unsubscribes, or debug a “the link did not work” report. You never call these endpoints from your own code: Releva builds the encrypted `{payload}` in each link when it renders the message, and the links need no `authorization` header. To unsubscribe a customer from your own system, use [Unsubscribe a customer with the API](https://releva.ai/documentation/reference/consent/unsubscribe-a-customer/).

## Where each link goes

| Link                                       | **Internal** mode                                                                                                  | **External** mode                                                                                                                                                                                                               |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{{unsubscribeLink}}` merge tag            | The subscription preferences page                                                                                  | The customer’s own `unsubscribeLink`, or your **Email Unsubscribe URL** with `encodedEmail`, `encodedPhoneNumber` and `url` added (see [External mode](https://releva.ai/documentation/reference/consent/unsubscribe-a-customer/#external-mode)) |
| `{{subscriptionManagementLink}}` merge tag | The subscription preferences page                                                                                  | Same as `{{unsubscribeLink}}`                                                                                                                                                                                                   |
| `List-Unsubscribe` email header            | `POST /api/v0/unsubscribe/oneclick/{payload}`, the one-click endpoint below                                        | Same as `{{unsubscribeLink}}`                                                                                                                                                                                                   |
| `{{subscribeLink}}` merge tag              | The double opt-in confirmation, see [Set up double opt-in](https://releva.ai/documentation/reference/consent/set-up-double-opt-in/) | Empty                                                                                                                                                                                                                           |

In **Internal** mode all links are served from your shop’s click-tracking host.

## The subscription preferences page

In **Internal** mode, `{{unsubscribeLink}}` and `{{subscriptionManagementLink}}` open a page titled **Subscription preferences**. It shows your shop’s user-visible subscriptions with the ones the customer holds switched on (all off for a customer who is not subscribed), in your shop’s language when that is Bulgarian, German, Greek or Romanian, and in English otherwise.

* **Save preferences** subscribes the customer with the subscriptions they switched on and removes the ones they switched off. Subscriptions that are not user-visible are left alone.
* **Unsubscribe from all lists**, or saving with every subscription switched off, unsubscribes the customer shop-wide, the same as `POST /api/v0/unsubscribe`.

You choose which subscriptions appear, and their captions, under **User Visible Subscriptions** in **Settings › Messaging**; see [Choose how Releva manages subscriptions](https://releva.ai/documentation/guides/consent/choose-how-releva-manages-subscriptions/).

The page reads and saves through `GET` and `POST /api/v0/profiles/subscriptions`. Both take the encrypted values from the link, not your keys, so they are for the page only.

## One-click unsubscribe (RFC 8058)

Releva adds two headers to every email it sends:

```plaintext
List-Unsubscribe-Post: List-Unsubscribe=One-Click
List-Unsubscribe: <https://click-tracking-host/api/v0/unsubscribe/oneclick/PAYLOAD>
```

When the customer selects the unsubscribe option of their mail client, the mail client posts to that URL. Releva unsubscribes the customer shop-wide, the same as `POST /api/v0/unsubscribe`. In **External** mode the header carries the same link as `{{unsubscribeLink}}`, so your page receives the request.

### Request

`POST /api/v0/unsubscribe/oneclick/{payload}`. No `authorization` header. The body must be `List-Unsubscribe=One-Click`, either form-encoded (as mail clients send it) or as JSON.

| Field              | Type   | Notes                        |
| ------------------ | ------ | ---------------------------- |
| `List-Unsubscribe` | string | Must be exactly `One-Click`. |

To test it, copy the URL from the `List-Unsubscribe` header of an email you received:

```plaintext
curl -X POST "$LIST_UNSUBSCRIBE_URL" \
  -H 'content-type: application/json' \
  -d '{ "List-Unsubscribe": "One-Click" }'
```

### Response

`200` with an empty body. The customer has been unsubscribed when the response arrives.

### Errors

Errors are plain text, not JSON.

| Status | When                                                          | Body                    |
| ------ | ------------------------------------------------------------- | ----------------------- |
| `400`  | The body is missing, or `List-Unsubscribe` is not `One-Click` | `Bad Request`           |
| `400`  | The payload is broken or changed                              | `Bad Request`           |
| `500`  | The opt-out could not be saved                                | `Internal Server Error` |

### The same URL opened in a browser

`GET /api/v0/unsubscribe/oneclick/{payload}` unsubscribes as well, and shows a page that redirects to your shop after 10 seconds. The page is in Bulgarian or Greek when that is your shop’s language, and in English otherwise.

| Status | Page title (English)       | Text                                                                                                               |
| ------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `200`  | **Unsubscribe Successful** | `Email address "maria@example.com" has been successfully unsubscribed.` (or `Phone number "..."` for a phone link) |
| `400`  | **Unsubscribe Failed**     | `The unsubscribe link you followed seems to be invalid.`                                                           |
| `500`  | **Unsubscribe Failed**     | `We encountered an internal error and were unable to unsubscribe you.`                                             |

Because a plain `GET` changes state, security scanners that open every link in an email can unsubscribe a customer this way.

## Limits

* No rate limits on these endpoints.
* One customer per link.

## Next steps

* [Unsubscribe a customer with the API](https://releva.ai/documentation/reference/consent/unsubscribe-a-customer/): Build the unsubscribe page your shop needs in External mode.
* [Choose how Releva manages subscriptions](https://releva.ai/documentation/guides/consent/choose-how-releva-manages-subscriptions/): Pick Internal or External and decide which subscriptions the preferences page shows.
* [Check a customer’s subscription status](https://releva.ai/documentation/guides/consent/check-a-customers-subscription-status/): Confirm an unsubscribe landed on the profile.