# One-Click Unsubscribe Management

One-Click Unsubscribe is a feature that allows email recipients to unsubscribe from your marketing emails with a single click, directly from their email client interface. This feature ensures compliance with email regulations like CAN-SPAM, GDPR, CASL, and RFC 8058, while improving user experience and email deliverability.

## Overview

When you enable managed unsubscribe, the system automatically:

- Adds RFC 8058-compliant headers (`List-Unsubscribe` and `List-Unsubscribe-Post`) to all outgoing emails
- Provides both HTTPS and mailto unsubscribe methods for maximum email client compatibility
- Securely processes unsubscribe requests through Treasure AI's infrastructure
- Records all unsubscribe events in a centralized database table for reporting and suppression


### What is a List-Unsubscribe Header?

A List-Unsubscribe header is an email header field that provides recipients with an easy way to opt out of future emails. It typically appears as an "Unsubscribe" link or button in the email client's interface, separate from the email content.

![Gmail Unsubscribe Button](/assets/one-click-unsubscribe-example-3.9717d98e00887d5d7a4b0da8c7c2544d890afa89afec68a9660c8240e386685e.5be018a0.png)

### Why is it Important?

Starting February 2024, Google and Yahoo began requiring that all bulk marketing emails support a one-click list-unsubscribe header. This requirement helps ensure better user experience, improved inbox placement, and compliance with modern email regulations.

## How It Works

### For Marketers

1. **Configure Sender Profile**: Enable "TD Managed Unsubscribe Link and Email" in your Sender Profile settings
2. **Set Redirect URL**: Specify your branded landing page URL where users will be redirected after unsubscribing
3. **Send Campaigns**: All emails sent using this sender profile will automatically include unsubscribe capabilities
4. **Track Events**: Monitor unsubscribe events in the `subscription_events` table


### For End Users

When a recipient receives your email, major email clients (Gmail, Yahoo, Outlook.com) will display an "Unsubscribe" button in the email header.

![Gmail Unsubscribe Button](/assets/one-click-unsubscribe-example-3.9717d98e00887d5d7a4b0da8c7c2544d890afa89afec68a9660c8240e386685e.5be018a0.png)

Clicking this button triggers one of two methods:

1. **HTTPS POST** (preferred by modern email clients): Sends a POST request directly to Treasure AI's unsubscribe endpoint
2. **Mailto** (fallback): Sends an email to Treasure AI's unsubscribe email address


Both methods securely process the unsubscribe request and record it in your database.

**Example User Experience:**

When a user clicks the unsubscribe button, they will see a confirmation dialog:

![Unsubscribe Confirmation Dialog](/assets/one-click-unsubscribe-example-1.21aa521ac35f1d5a835385b538141bec3f20c6fedc390f03d39495a0073dae55.5be018a0.png)

After confirming, they will receive a success message:

![Unsubscribe Success Message](/assets/one-click-unsubscribe-example-2.3382503c6421d212245013ae68720526047695b60e426c78e64bb986fb37cb70.5be018a0.png)

## Set Up One-Click Unsubscribe

### Prerequisites

- A verified email domain configured in Engage Studio
- A sender profile created for your campaigns
- A static HTTPS landing page for unsubscribe confirmation, hosted on your own infrastructure or with [Landing Pages](/products/marketing-cloud/engage-studio/landing-pages)


Note
Landing Pages can host the static confirmation page, but they do not process unsubscribe requests. Before submitting the POST request, your page must validate `postTo` against the exact HTTPS unsubscribe endpoints listed below, including the `/unsubscribe` path. Do not submit a URL from the query parameter without strict origin validation.

### Configuration Steps

1. Navigate to **Sending Configurations** > **Sender Profiles**
2. Create a new sender profile or edit an existing one
3. Go to the **Unsubscribe Header** tab
4. Select **"TD Managed Unsubscribe Link and Email"**
5. Enter your **Redirect URL** (must start with `https://`)
Example: `https://www.yourcompany.com/unsubscribe-confirmation`
This is the customer landing page where users will be redirected after clicking unsubscribe.
6. Click **Save**


### Email Headers Generated

When you send an email using this configuration, Treasure AI automatically adds the following headers:

```
List-Unsubscribe: <mailto:unsubscribe@engage-subscription.{region}.treasuredata.com?subject={token}>, <https://engage-subscription.{region}.treasuredata.com/unsubscribe?token={token}>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
```

These headers tell email clients how to handle one-click unsubscribe requests.

**Note**: `{region}` will be automatically replaced with your Treasure AI region (us01, eu01, ap03, or ap02).

## Using Template Variables

You can embed unsubscribe links directly in your email content using special template variables. These variables are available when managed unsubscribe is enabled:

### Available Variables

| Variable | Description | Example Output |
|  --- | --- | --- |
| `{{sender.unsubscribe_url}}` | HTTPS unsubscribe URL with secure token | `https://yourlandingpage.com?postTo=https%3A%2F%2Fengage-subscription.{region}.treasuredata.com%2Funsubscribe%3Ftoken%3Dabc123` |
| `{{sender.unsubscribe_email}}` | Mailto unsubscribe address | `unsubscribe@engage-subscription.{region}.treasuredata.com` |
| `{{sender.unsubscribe_email_subject}}` | Subject line for mailto unsubscribe (contains the secure token) | `abc123` |


**Note**: `{region}` in the examples will be automatically replaced with your actual Treasure AI region code.

### Example Usage in Email Template

**HTTPS Unsubscribe:**

```html
<p>
  If you no longer wish to receive these emails,
  <a href="{{sender.unsubscribe_url}}">click here to unsubscribe</a>.
</p>
```

**Mailto Unsubscribe:**

To enable unsubscribe via email, you must include the token in the email subject line:

```html
<p>
  If you no longer wish to receive these emails,
  <a href="mailto:{{sender.unsubscribe_email}}?subject={{sender.unsubscribe_email_subject}}">
    unsubscribe via email
  </a>.
</p>
```

**Using Visual Editor:**

When using the Visual Editor to create email templates, you can insert mailto unsubscribe links through the link insertion dialog:

1. Select the text you want to turn into an unsubscribe link
2. Click the link icon in the toolbar
3. Select **E-MAIL** as the Link Type
4. Fill in the following fields:
  - **Email**: `{{sender.unsubscribe_email}}`
  - **Subject**: `{{sender.unsubscribe_email_subject}}`
  - **Text to display**: Your desired link text (e.g., "Unsubscribe email")
5. Click **OK**


![Visual Editor - Mailto Unsubscribe Link Configuration](/assets/visual-editor-mailto-unsubscribe.e2a512a4b254413026f5cd1dd61c847a06ddf95e3b383de326bdc5aafe53f256.5be018a0.png)

Important
When using `{{sender.unsubscribe_url}}`, the URL automatically includes a `postTo` parameter. Your landing page must parse it as a URL and allow only the documented Treasure AI HTTPS unsubscribe origins with the `/unsubscribe` path before submitting the POST request. Reject any other origin, path, protocol, credentials, or fragment.

## Unsubscribe Event Data

All unsubscribe events are automatically recorded in the `subscription_events` table within your email domain's database. This allows you to track unsubscribe activity, analyze trends, and build workflows to exclude unsubscribed users from future campaigns.

For detailed information about the subscription events schema, queries, and best practices, see [Subscription Events Table](/products/marketing-cloud/engage-studio/channels/email/subscription-events-table).

## Building Custom Landing Pages

When users click the unsubscribe link in your email body (using `{{sender.unsubscribe_url}}`), they are redirected to your custom landing page. Your page must complete the unsubscribe process by submitting a POST request to Treasure AI.

Important
Landing Pages can host a static unsubscribe confirmation page, but they do not provide native form submission or unsubscribe processing. Your page must extract the `postTo` parameter and submit the required POST request.

### Landing Page Requirements

1. **Extract the Token**: Parse the `postTo` parameter from the URL
2. **Validate the Endpoint**: Allow only the documented Treasure AI HTTPS unsubscribe origins with the `/unsubscribe` path; reject every other origin, path, protocol, credential, and fragment
3. **Display Confirmation**: Show a confirmation message or button
4. **Submit POST Request**: Send a POST request to the validated Treasure AI unsubscribe endpoint


### Example Landing Page Implementation

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Unsubscribe Confirmation</title>
    <style>
        body {
            font-family: Arial, sans-serif;
            max-width: 600px;
            margin: 50px auto;
            padding: 20px;
            text-align: center;
        }
        .success {
            color: #2e7d32;
            background-color: #e8f5e8;
            padding: 20px;
            border-radius: 8px;
            margin: 20px 0;
        }
        .error {
            color: #d32f2f;
            background-color: #ffebee;
            padding: 20px;
            border-radius: 8px;
            margin: 20px 0;
        }
        .loading {
            color: #1976d2;
        }
        #postForm {
            display: none;
        }
    </style>
</head>
<body>
    <h1>Unsubscribe</h1>
    <div id="result">
        <p class="loading">Processing your unsubscribe request...</p>
    </div>

    <!-- Hidden form for automatic submission -->
    <form id="postForm" method="POST" target="responseFrame"></form>
    <iframe name="responseFrame" style="display: none;"></iframe>

    <script>
        const ALLOWED_UNSUBSCRIBE_ORIGINS = new Set([
            'https://engage-subscription.us01.treasuredata.com',
            'https://engage-subscription.eu01.treasuredata.com',
            'https://engage-subscription.treasuredata.co.jp',
            'https://engage-subscription.ap02.treasuredata.com'
        ]);

        function getUrlParameter(name) {
            const urlParams = new URLSearchParams(window.location.search);
            return urlParams.get(name);
        }

        function displayMessage(message, type = 'success') {
            const resultDiv = document.getElementById('result');
            resultDiv.innerHTML = `<div class="${type}">${message}</div>`;
        }

        function validatePostTo(value) {
            const url = new URL(value);

            if (
                url.protocol !== 'https:' ||
                !ALLOWED_UNSUBSCRIBE_ORIGINS.has(url.origin) ||
                url.pathname !== '/unsubscribe' ||
                url.username ||
                url.password ||
                url.hash ||
                !url.searchParams.get('token')
            ) {
                throw new Error('Invalid unsubscribe endpoint');
            }

            return url.href;
        }

        function submitForm(url) {
            const form = document.getElementById('postForm');
            form.action = url;
            form.submit();

            // Show success message after submission
            setTimeout(() => {
                displayMessage(`
                    <h2>Thank You!</h2>
                    <p>You have been successfully unsubscribed from our emails.</p>
                    <p>You will no longer receive marketing emails from us.</p>
                `, 'success');
            }, 1000);
        }

        function init() {
            const postTo = getUrlParameter('postTo');

            if (!postTo) {
                displayMessage(`
                    <strong>Error: Invalid unsubscribe link</strong><br>
                    Please contact support if you continue to receive unwanted emails.
                `, 'error');
                return;
            }

            // Validate the endpoint against the explicit allowlist before POSTing.
            try {
                submitForm(validatePostTo(postTo));
            } catch (e) {
                displayMessage(`
                    <strong>Error: Invalid unsubscribe link</strong><br>
                    Please contact support if you continue to receive unwanted emails.
                `, 'error');
            }
        }

        window.addEventListener('DOMContentLoaded', init);
    </script>
</body>
</html>
```

Note
Customize the CSS and HTML according to your brand design requirements.

### Unsubscribe Endpoint

**Method**: `POST`

**Endpoint URLs by Region**:

| Region | Endpoint URL |
|  --- | --- |
| US | `https://engage-subscription.us01.treasuredata.com/unsubscribe` |
| EU | `https://engage-subscription.eu01.treasuredata.com/unsubscribe` |
| Tokyo | `https://engage-subscription.treasuredata.co.jp/unsubscribe` |
| Korea | `https://engage-subscription.ap02.treasuredata.com/unsubscribe` |


**Parameters**:

- `token` (query parameter): The unique encrypted token from the email


**Example Request**:

```
POST https://engage-subscription.{region}.treasuredata.com/unsubscribe?token={token}
```

**Responses**:

Success (200):

```json
{
  "message": "Success"
}
```

Error (400):

```json
{
  "message": "Invalid request"
}
```

**Note**: The endpoint URL is automatically included in the `postTo` parameter when using `{{sender.unsubscribe_url}}`. Accept only the four HTTPS origins listed above with the `/unsubscribe` path, require the `token` query parameter, and reject any other URL before submitting the POST request.

## Token Security and Expiration

Each unsubscribe link contains a unique, secure token that:

- **Is valid for 60 days** after the email is sent
- **Is encrypted** to protect user privacy and prevent tampering
- **Can only be used** to unsubscribe the specific recipient who received the email


**How tokens behave in different scenarios:**

- **Expired tokens (>60 days)**: POST request returns `Invalid request` (400), no event is recorded, user should contact support or use an alternative method
- **Duplicate requests**: All requests process successfully within the validity period, multiple events are recorded in `subscription_events`, the operation is idempotent (unsubscribe remains unsubscribe)
- **Invalid or tampered tokens**: Request returns `Invalid request` (400), no data is written to the database.


## Frequently Asked Questions

### Which email clients support one-click unsubscribe?

Different email clients support different unsubscribe methods:

| Email Client | Mailto Header | HTTPS Header | One-Click (RFC 8058) |
|  --- | --- | --- | --- |
| Gmail | Supported* | Supported | Supported |
| Gmail Mobile | Not supported | Not supported | Not supported |
| Apple Mail (iOS/macOS) | Supported | Supported | Supported |
| Outlook.com | Supported | Not supported | Not supported |
| Yahoo! Mail | Supported* | Not supported | Supported |
| Samsung Mail | Not supported | Not supported | Not supported |


*Gmail and Yahoo will eventually deprecate mailto and support only one-click HTTPS.

**Best Practice**: Always include both HTTPS and mailto headers for maximum compatibility, and add an unsubscribe link in your email body using `{{sender.unsubscribe_url}}` for clients that don't support headers.

### Why isn't the unsubscribe button showing in Gmail?

The unsubscribe button may not appear due to:

- Low sender reputation or domain reputation
- Insufficient email volume (Gmail requires consistent volume)
- Missing or malformed headers


**How to verify**:

- Use "Show Original" in Gmail to check that headers are present
- Verify domain authentication (SPF, DKIM, DMARC)
- Improve sender reputation by reducing spam complaints


**Testing alternative**: Use Apple Mail (iPhone/iPad/Mac) to test unsubscribe functionality, as it reliably displays the unsubscribe button and supports both mailto and HTTPS POST headers.

## Current Limitations

The One-Click Unsubscribe feature currently has the following limitations:

- **Single Global Subscription Group**: All unsubscribes currently apply to a single "Global" subscription group. Topic-based unsubscribe management (allowing users to unsubscribe from specific email types) will be available in future releases.
- **Opt-Out Only**: Currently only opt-out (unsubscribe) events are supported. Opt-in (resubscribe) functionality is not yet available and must be managed through custom implementations.
- **Email Channel Only**: Currently limited to email campaigns. Support for SMS, push notifications, and other channels will be added in future releases.
- **Static Landing Page Required**: Customers need a static HTTPS landing page for unsubscribe confirmation. You can host the page on your own infrastructure or use [Landing Pages](/products/marketing-cloud/engage-studio/landing-pages); native unsubscribe processing and preference centers are not part of Landing Page Delivery.
- **Manual Suppression**: Marketers must manually build workflows to exclude unsubscribed users from campaigns. Unsubscribed users must be integrated as Attribute properties to enable filtering. Automatic suppression at the delivery layer will be added in future releases.


## Related Documentation

- [Subscription Events Table](/products/marketing-cloud/engage-studio/channels/email/subscription-events-table)
- [Email Sender Configuration](/products/marketing-cloud/engage-studio/channels/email/email-sender-configuration)
- [Email Domain Configuration](/products/marketing-cloud/engage-studio/channels/email/email-domain-configuration)
- [Email Deliverability & Authentication](/products/marketing-cloud/engage-studio/channels/email/email-deliverability-authentication)
- [Email Delivery Events Table](/products/marketing-cloud/engage-studio/channels/email/email-delivery-events-table)


## Support

If you encounter issues with One-Click Unsubscribe, contact Treasure AI support with:

- Campaign ID
- Token value (if applicable)
- Timestamp of the unsubscribe attempt
- Any error messages received