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
  • 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)
    • 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 - Two separate events are tracked:

    • ACTION_SAVED_FREQUENCY - When frequency is saved
    • ACTION_SAVED_TOPICS - When topics are saved

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

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"

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 (radio buttons for frequency, checkboxes for topics) based on your team-wide configuration. This ensures consistency and makes it easy to update options across all pages.

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 (checkboxes) based on your team's topic configs
  • The generated HTML includes proper form structure with name="emailTopics" attributes
  • 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

  • Pre-select the most common frequency option
  • Pre-select all topics by default (users can uncheck what they don't want)

4. Show Success Feedback

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

5. 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