One-Click Unsubscribe Management

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

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.

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.

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:

After confirming, they will receive a success message:

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

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

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

Example Usage in Email Template

HTTPS Unsubscribe:

<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:

<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

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.

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.

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

<!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>

Unsubscribe Endpoint

Method: POST

Endpoint URLs by Region:

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):

{
  "message": "Success"
}

Error (400):

{
  "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:

*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
• Email Sender Configuration
• Email Domain Configuration
• Email Deliverability & Authentication
• 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