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.

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:

<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