# Understanding the Unsubscribe and Preferences System

## Overview

The **Unsubscribe and Preferences** system gives recipients control over
the messages they receive and helps you maintain good sending practices.
Each Mass Email Notification can include an unsubscribe mechanism—either
a simple automatic footer or a fully customizable preferences form. This
feature improves trust, ensures compliance with email standards, and
reduces the risk of messages being flagged as spam.

All of this is optional. By default, nothing changes—you can continue
sending emails exactly as before if you prefer not to include
unsubscribe features.

There are two levels of functionality:

- **Free Version** – can automatically add a standard unsubscribe footer
  to every message (optional).
- **Premium Version** – expands this with custom link text, custom
  landing pages, preferences forms, and per-feed unsubscribe logic,
  along with the ability to resubscribe users if needed.

------------------------------------------------------------------------

## Why It Matters

Providing a visible unsubscribe option is more than courtesy—it’s a sign
of professionalism.
It helps you:

- Stay compliant with CAN-SPAM, GDPR, and similar regulations.
- Protect your sender reputation and deliverability.
- Maintain trust with your audience.
- Avoid having your domain or email account blacklisted for spam-like
  behavior.

------------------------------------------------------------------------

## How the System Works

Each outgoing mass email includes a unique link that identifies the
recipient. When the link is clicked, the plugin updates the
**Unsubscribe List** so that address is skipped in future sends (or
temporarily paused, depending on configuration).

The **Suppressions** tab inside your dashboard provides a full overview
of these entries:

- **Email** – the address that unsubscribed or was paused.
- **Global Status** – whether the user is globally unsubscribed or
  paused.
- **Feeds** – which specific feeds or campaigns they opted out of.
- **Last Updated** – when the change occurred.

Premium users also see **Remove** buttons to manually resubscribe or
clear paused statuses.

------------------------------------------------------------------------

## Free vs Premium Capabilities

<figure class="wp-block-table">
<table class="has-fixed-layout">
<thead>
<tr class="header">
<th>Feature</th>
<th>Free</th>
<th>Premium</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>Auto-appended footer</td>
<td>✅</td>
<td>✅</td>
</tr>
<tr class="even">
<td>Customize link text</td>
<td>❌</td>
<td>✅</td>
</tr>
<tr class="odd">
<td>Custom landing page</td>
<td>❌</td>
<td>✅</td>
</tr>
<tr class="even">
<td>Merge tag–based unsubscribe links</td>
<td>❌</td>
<td>✅</td>
</tr>
<tr class="odd">
<td>Preferences form support</td>
<td>❌</td>
<td>✅</td>
</tr>
<tr class="even">
<td>"Pause until" option</td>
<td>❌</td>
<td>✅</td>
</tr>
<tr class="odd">
<td>Segment by feed or category</td>
<td>❌</td>
<td>✅</td>
</tr>
<tr class="even">
<td>Remove users manually</td>
<td>❌</td>
<td>✅</td>
</tr>
<tr class="odd">
<td>Unsubscribe headers for Gmail</td>
<td>❌</td>
<td>✅ (experimental)</td>
</tr>
</tbody>
</table>
</figure>

------------------------------------------------------------------------

## Core Concepts

### Unsubscribe

Removes a recipient from all or selected feeds. Once unsubscribed, they
will no longer receive related mass emails unless cleared from the
Unsubscribe list.

### Pause

Temporarily halts emails until a selected date or after a specified
number of days. When the date or duration passes, the user automatically
becomes eligible to receive messages again.

### Preferences Form

A custom Gravity Form that allows recipients to control what kinds of
messages they receive. When a user clicks the link in an email, their
address is pre-filled in the email field. Optional fields like *Pause
Until* or *Control Field* (checkboxes, radio, select) can be added to
give recipients more options.

### Control Field

A multi-choice field that lets users unsubscribe from specific
categories (e.g., marketing, updates). Each choice can be mapped to one
or more feeds, allowing segmented unsubscribes.

### Unsubscribe Headers (Gmail and Others)

When enabled, the plugin adds standard **List-Unsubscribe headers** to
outgoing emails. This can make a one-click **Unsubscribe** button appear
in Gmail and other email clients.

This feature is **still in testing** and depends on several factors:

- Gmail must be able to **reach the unsubscribe URL** (it will not work
  in local or private development environments).
- The email must meet Gmail’s **criteria for promotional or bulk
  messages**; purely transactional emails often won’t show the button.
- Your **domain reputation and sending score** also influence whether
  the button appears.
- Some **third-party plugins or SMTP services** may strip or overwrite
  headers.

It’s safe to enable this option—it won’t cause harm—but Gmail may or may
not display the Unsubscribe button depending on the above conditions.

------------------------------------------------------------------------

## Typical Setup Patterns

### Simple Compliance (Free)

Enable the default footer to automatically include an unsubscribe link
at the bottom of every mass email.

### Custom Experience (Premium)

Change the link text and set your own landing page to match your site
branding.

### Advanced Segmentation (Premium)

Use merge tags to create links that lead to a preferences form.
Recipients can choose what to receive or pause messages.

### Hybrid Setup

Combine both footer and merge-tag methods—for example: *“Click here to
unsubscribe”* and *“or here to manage your preferences”*.

------------------------------------------------------------------------

## Admin Experience

Admins can view all unsubscribed or paused recipients under **GravityOps → Mass Notifications → Suppressions**.
The tab shows:

- **Email**
- **Global Status** (paused/unsubscribed)
- **Feeds** affected
- **Last Updated**
- (Premium) **Remove / Remove All** actions

Removing a record immediately re-enables the user for future sends.

------------------------------------------------------------------------

## Summary & Best Practices

- Always keep an unsubscribe option active—never remove it manually.
- Use clear, user-friendly wording ("Manage preferences" often performs
  better than "Unsubscribe").
- Test your links and landing pages to confirm redirects work as
  intended.
- Enable Gmail Unsubscribe Headers for better compliance (even if Gmail
  doesn’t always display them).
- Periodically review your Unsubscribe list to keep it accurate and
  organized.

The unsubscribe and preferences system makes your emails more
transparent, compliant, and user-friendly—all while protecting your
deliverability and brand reputation.
