# 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 Treasure Data 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 Data'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 "Treasure Data 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 Data's unsubscribe endpoint
2. **Mailto** (fallback): Sends an email to Treasure Data'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)

## Setting Up TD Managed One-Click Unsubscribe

### Prerequisites

- A verified email domain configured in Engage Studio
- A sender profile created for your campaigns
- A customer-hosted landing page (HTTPS required) for unsubscribe confirmation


Note
Landing pages must be hosted by the customer. Treasure Data-hosted landing pages are planned for a future release.

### 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 **"Treasure Data 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 Data 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 Data 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 TD 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 Data 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 that contains the TD unsubscribe endpoint. Your landing page should extract this parameter and submit a POST request to complete the unsubscribe process.

## 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 Data.

Important
Landing pages must be hosted by the customer on their own infrastructure. Treasure Data does not currently provide hosted landing pages, but this functionality is planned for a future release.

### Landing Page Requirements

1. **Extract the Token**: Parse the `postTo` parameter from the URL
2. **Display Confirmation**: Show a confirmation message or button
3. **Submit POST Request**: Send a POST request to the TD 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>
        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 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 URL format
            try {
                new URL(postTo);
                submitForm(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}}`. Your landing page should extract this URL and submit a POST request to it.

## 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.
- **Customer-Hosted Landing Pages Required**: Customers must host their own landing pages for unsubscribe confirmation. Treasure Data-hosted landing pages and preference centers are planned for a future release.
- **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 Data support with:

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