# User Preferences Feature

## Overview

The User Preferences feature allows subscribers to customize their email experience directly from your unsubscribe page. Instead of unsubscribing, subscribers can:

- **Adjust email frequency** - Choose how often they receive emails (weekly, monthly, etc.)
- **Select email topics** - Choose which types of emails they want to receive (one or many, depending on your page setting)
- **Stay subscribed** - Remain on your list with their preferred settings

This feature helps you retain more subscribers by giving them control over their email experience.

## How It Works

### Subscriber Experience

1. **Initial Page** - When a subscriber clicks unsubscribe, they see your initial page with options
2. **Preferences Page** - If they click "Manage Email Preferences", they're taken to a preferences page
3. **Customization** - They can:
   - Select their preferred email frequency (e.g., weekly, monthly)
   - Choose which email topics they want (e.g., promotions, newsletters, updates)—one or multiple, depending on your page's topic selection mode
   - Save their preferences
4. **Confirmation** - After saving, they see a success message and remain subscribed

### Behind the Scenes

When preferences are saved:

1. **Klaviyo Profile Updated** - The subscriber's Klaviyo profile is updated with:
   - `email_frequency` - Their selected frequency
   - `email_topics` - Comma-separated list of selected topics
   - `stay_subscribed` - Set to `true`

2. **Database Storage** - Preferences are stored in the database for:
   - Analytics tracking
   - Pre-filling preferences on future visits
   - Reporting and insights

3. **Analytics Events** - Separate events are tracked depending on how preferences were saved:
   - `ACTION_SAVED_FREQUENCY` / `ACTION_SAVED_TOPICS` - When saved on the unsubscribe page
   - `ACTION_ONE_CLICK_SAVED_FREQUENCY` / `ACTION_ONE_CLICK_SAVED_TOPICS` - When saved via a one-click link from an email

You can also apply preferences from **email deep links** so subscribers never open the form. See [One-Click Preferences](./one-click-preferences.md).

## Setting Up Preferences

### 1. Configure Frequency Options

Go to **Settings → User Preferences → Frequencies tab**:

- Add or edit frequency options (e.g., "Weekly", "Monthly", "Quarterly")
- Set the number of days for each frequency
- Reorder options by dragging
- Enable/disable specific options
- Optionally set **Default when not set** — pre-selected on the unsubscribe page and storefront preference UI for subscribers who have not chosen a frequency yet (does not change a saved preference until they save). Leave as **Unset** if you do not want a pre-selection.

### 2. Configure Topic Options

Go to **Settings → User Preferences → Topics tab**:

- Add or edit topic options (e.g., "Promotions", "Newsletters", "Product Updates")
- Customize labels for each topic
- Reorder options by dragging
- Enable/disable specific options

### 3. Create Topic Exclusion Segments (Klaviyo)

In the Topics tab, scroll to the **Segments** section. Create topic exclusion segments for each topic. These segments contain subscribers who have opted out of that topic. In Klaviyo campaigns and flows:

- **Send to:** Use any main segment (e.g., "All Subscribers", "Newsletter List")
- **Don't send to:** Add the **matching** topic exclusion segment—the one that corresponds to the type of email you're sending (e.g., for a newsletter campaign, add `LC - Exclude Topic: Newsletters`; for a sales campaign, add `LC - Exclude Topic: Sales & Discounts`)

This lets you use your existing segments while respecting subscriber topic preferences.

### 4. Create Frequency Exclusion Segments (Klaviyo)

In the Frequencies tab, scroll to the **Segments** section. Create frequency exclusion segments for each frequency. These segments contain subscribers who chose a less-frequent option. In Klaviyo campaigns and flows:

- **Send to:** Use any main segment
- **Don't send to:** Add **every** LC - Exclude Frequency segment (e.g., `LC - Exclude Frequency: Weekly`, `LC - Exclude Frequency: Monthly`, etc.)—you need all of them to enforce frequency limits across your audience

### 5. Add Preferences Page to Your Unsubscribe Page

In your unsubscribe page editor:

1. Add a "Manage Email Preferences" button with `data-action="go-to-preferences"`
2. Create a preferences page using the template variables:
   - Use `{{preferencesFrequencies}}` to automatically generate frequency selection options
   - Use `{{preferencesTopics}}` to automatically generate topic selection options
   - Add save buttons with `data-action="save-frequency"` and `data-action="save-topics"`

#### Topic selection mode (per page)

In the page editor, open **Settings → Subscriber preferences → Topic selection**:

- **Multiple topics (checkboxes)** — default; subscribers can select any combination of topics
- **Single topic (radio buttons)** — subscribers pick exactly one topic

Topic options themselves are still configured team-wide under **Settings → User preferences → Topics**. The page setting only controls whether subscribers can pick one or many.

When single-topic mode is enabled, headings and button labels on the preferences page use singular copy (e.g., "Email Topic", "Save Topic") automatically.

**Example preferences page HTML:**

```html
<div class="preferences-form">
  <div class="preferences-section">
    <h3>Email Frequency</h3>
    <p>How often would you like to hear from us?</p>
    {{preferencesFrequencies}}
    <button data-action="save-frequency">Save Frequency</button>
  </div>

  <div class="preferences-section">
    <h3>Email Topics</h3>
    <p>What would you like to hear about?</p>
    {{preferencesTopics}}
    <button data-action="save-topics">Save Topics</button>
  </div>
</div>
```

The template variables automatically generate the correct HTML form elements based on your configuration:

- **Frequency** — radio buttons from your team-wide frequency configs
- **Topics** — checkboxes when the page uses multiple-topic mode (default), or radio buttons when the page uses single-topic mode

This ensures consistency and makes it easy to update options across all pages. In single-topic mode, section titles and save button labels may use singular copy automatically.

> **Note:** For advanced use cases where you want custom options that differ from your team-wide settings, you can manually create form elements with `name="emailFrequency"` and `name="emailTopics"`, but this is generally not recommended as it won't sync with your team configuration.

### 6. Use Preferences Components

The page editor includes built-in components:

- **Frequency Options** - Pre-built frequency selection component (uses `{{preferencesFrequencies}}`)
- **Topic Options** - Pre-built topic selection component (uses `{{preferencesTopics}}`)
- **Preferences Frequencies** - Full preferences page with frequency options
- **Preferences Topics** - Full preferences page with topic options

## Template Variables

When building custom preferences pages, use these template variables:

### Frequency Variables

- `{{preferencesFrequencies}}` - Automatically generates HTML for frequency selection (radio buttons) based on your team's frequency configs
- The generated HTML includes proper form structure with `name="emailFrequency"` attributes
- Options are automatically pulled from your team-wide frequency configuration

### Topic Variables

- `{{preferencesTopics}}` - Automatically generates HTML for topic selection based on your team's topic configs and the page's topic selection mode
  - **Multiple topics** (default): checkboxes (`name="emailTopics"`)
  - **Single topic**: radio buttons (`name="emailTopics"`)
- Options are automatically pulled from your team-wide topic configuration

### Other Variables

- `{{selectedFrequency}}` - Currently selected frequency (if user has saved preferences) - used by `PreferencesInitializer` component
- `{{selectedTopics}}` - Array of currently selected topics (if user has saved preferences) - used by `PreferencesInitializer` component

## Best Practices

### 1. Make Preferences Easy to Find

- Place the "Manage Email Preferences" button prominently on your initial page
- Use clear, action-oriented text like "Manage Email Preferences" or "Customize My Emails"

### 2. Keep Options Simple

- Limit frequency options to 3-5 choices
- Limit topic options to 5-7 choices
- Use clear, descriptive labels

### 3. Provide Defaults

- Use **Default when not set** on the Frequencies tab if you want a frequency pre-selected for new subscribers
- **Multiple topics:** pre-select all topics by default (users can uncheck what they don't want)
- **Single topic:** pre-select the first topic by default

### 4. Choose single vs. multiple topics

- Use **multiple topics** when subscribers may want several content types (e.g., promotions + newsletters)
- Use **single topic** when categories are mutually exclusive or you want a clear primary preference (e.g., "Which line of business do you care about?")

### 5. Show Success Feedback

- Display a clear success message after saving
- Confirm what was saved (e.g., "Your preferences have been saved!")

### 6. Allow Partial Updates

- Users can save frequency and topics separately
- Don't require both to be set at once

## Troubleshooting

### Preferences Not Saving

- Check that the save button has the correct `data-action` attribute
- Verify the API endpoint is accessible
- Check browser console for errors

### Preferences Not Showing

- Ensure preferences page is included in your unsubscribe page
- Verify the `PreferencesInitializer` component is included
- Check that saved preferences exist in the database

### Klaviyo Profile Not Updating

- Verify Klaviyo integration is connected
- Check that the subscriber's profile exists in Klaviyo
- Review Klaviyo API logs for errors

## Related Features

- [One-Click Preferences](./one-click-preferences.md) - Apply topics/frequency from email links
- [Analytics](./analytics.md) - Track preferences-related events
- [Subscriber Experience](./subscriber-experience.md) - Understand the full subscriber journey
- [Getting Started](./getting-started.md) - Initial setup guide