User Communication Preferences

Give users control over what communications they receive and how you use their data. This guide covers capturing, storing, and respecting preferences in Zixflow.

What Are User Preferences?

Preferences are settings that control:

Which channels you can use (email yes, SMS no)
What types of messages they want (product updates yes, promotions no)
How frequently they hear from you
When you can reach them (quiet hours)

Ask once, respect forever. Honor opt-outs immediately, store them permanently, and apply them across campaigns.

Why Preferences Matter

For users: Control fatigue, choose channels, set frequency limits. For you: Higher engagement, legal compliance (GDPR, CAN-SPAM, CCPA), better deliverability.

Types of Preferences

1. Channel Preferences (What to Reach Them On)

Definition: Which communication channels the user accepts messages through. Each channel has its own opt-out field and timestamp stored on the user profile. Channel opt-out fields:

Channel	Field	Default state
Email	`email_opt_out`	`UNKNOWN` (pending confirmation)
SMS	`sms_opt_out`	`NOT_OPTED_OUT`
WhatsApp	`whatsapp_opt_out`	`NOT_OPTED_OUT`
RCS	`rcs_opt_out`	`NOT_OPTED_OUT`
Push	`push_opt_out`	`NOT_OPTED_OUT`

Each field uses one of three values:

1 — NOT_OPTED_OUT: user is reachable (default for SMS/WhatsApp/RCS/Push)
2 — OPTED_OUT: user explicitly opted out — all sends suppressed
3 — UNKNOWN: intent not yet established (default for Email)

Each channel also stores an _opt_out_at timestamp:

// User opts out of SMS
Zixflow.instance.setProfileAttributes({
  'sms_opt_out': 2,
  'sms_opt_out_at': DateTime.now().toIso8601String(),
});

// User opts out of push
Zixflow.instance.setProfileAttributes({
  'push_opt_out': 2,
  'push_opt_out_at': DateTime.now().toIso8601String(),
});

// User confirms email opt-in
Zixflow.instance.setProfileAttributes({
  'email_opt_out': 1,  // NOT_OPTED_OUT
});

Important: Email defaults to UNKNOWN rather than NOT_OPTED_OUT because email requires explicit confirmation before you can assume consent (GDPR). All other channels default to NOT_OPTED_OUT since they require an explicit action (push permission grant, phone number submission) to receive messages at all.

2. Category Preferences (What Type of Messages)

Definition: What topics or types of content the user wants to receive. Category preferences are custom attributes — you define the categories that make sense for your product and store them as profile attributes. Example:

Zixflow.instance.setProfileAttributes({
  'subscribed_to_promotions': false,      // No sales/discounts
  'subscribed_to_product_updates': true,  // Product news yes
  'subscribed_to_newsletter': true,       // Weekly newsletter yes
  'subscribed_to_transactional': true,    // Order updates (always on)
});

Why categories matter:

User might want product updates but not promotional emails
Transactional messages (order confirmations, password resets) typically can’t be opted out
GDPR requires granular control (not just “all or nothing”)

3. Frequency Preferences (How Often to Message)

Definition: Controls how often users receive non-critical messages. Like categories, frequency preferences are custom attributes you define and check when building campaigns. Example:

Zixflow.instance.setProfileAttributes({
  'email_frequency': 'daily_digest',  // immediate | daily_digest | weekly_digest | never
  'push_frequency': 'immediate',
  'max_emails_per_week': 3,
});

4. User Suppression (Block All Channels)

Suppression is a server-side lifecycle event that blocks all outbound messages for a user across every channel, regardless of their individual opt-out settings.

Lifecycle Event	Effect
`User Suppressed`	Sets `is_suppressed = true` on profile — no messages sent on any channel
`User Unsuppressed`	Clears the flag — message delivery resumes

When to use suppression:

User requests complete silence (GDPR “right to be forgotten” equivalent)
Account fraud/abuse detected
Account is past-due / in bad standing

Suppression is distinct from channel opt-out: opt-out is per-channel and set by the user, suppression is workspace-controlled and blocks everything.

Capturing Preferences

Method 1: In-App Preference Center

Best for: Letting users manage their own preferences (GDPR requirement) Example UI:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Notification Preferences
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Email Preferences:
☑ Product updates & new features
☑ Weekly newsletter
☐ Promotions & discounts
☑ Order & account notifications

Push Notifications:
☑ New messages
☑ Friend activity
☐ Daily summary

[Save Preferences]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Implementation:

// User clicks "Save Preferences"
function savePreferences() {
  const prefs = {
    subscribed_to_product_updates: document.getElementById('product_updates').checked,
    subscribed_to_newsletter: document.getElementById('newsletter').checked,
    subscribed_to_promotions: document.getElementById('promotions').checked,
    subscribed_to_transactional: true,  // Always on
    
    push_new_messages: document.getElementById('push_messages').checked,
    push_friend_activity: document.getElementById('push_activity').checked,
    push_daily_summary: document.getElementById('push_summary').checked
  };
  
  Zixflow.setProfileAttributes(prefs);
  
  // Also track that they updated preferences
  Zixflow.track('Updated Preferences', { changes: prefs });
}

Method 2: Email Unsubscribe Links

Best for: One-click opt-out from email campaigns (CAN-SPAM requirement) Example flow:

User receives promotional email
Clicks “Unsubscribe” link at bottom
Lands on preference page: “You’ve unsubscribed from promotional emails”
Option to manage granular preferences or unsubscribe from all

Implementation:

// Unsubscribe page loads
const urlParams = new URLSearchParams(window.location.search);
const userId = urlParams.get('user_id');
const category = urlParams.get('category');  // e.g., "promotions"

// Immediately unsubscribe
Zixflow.identify({ 
  userId: userId,
  traits: {
    [`subscribed_to_${category}`]: false,
    unsubscribed_at: new Date().toISOString()
  }
});

Zixflow.track('Unsubscribed', { 
  category: category,
  source: 'email_link' 
});

// Show confirmation
document.getElementById('message').innerText = 
  `You've been unsubscribed from ${category} emails.`;

Method 3: Onboarding Preference Collection

Best for: Setting preferences early (before first campaign) Example onboarding screen:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  How would you like to hear from us?
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

☑ Email me about new features (weekly)
☑ Push notifications for messages (real-time)
☐ SMS me about special offers

[Continue]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Why this works:

Sets expectations early (“we’ll email you weekly”)
Reduces future unsubscribes (they opted in knowingly)
Better engagement (only contact people who agreed)

Respecting Preferences in Campaigns

Transactional vs. Marketing Messages

Transactional messages (can’t be opted out):

Order confirmations
Password resets
Account security alerts
Billing notifications

Why: User needs these to use your service (GDPR carve-out) Marketing messages (must respect opt-out):

Newsletters
Promotional emails
Feature announcements
Re-engagement campaigns

Implementation:

// Transactional: Always send (ignore preferences)
sendEmail({
  to: user.email,
  template: 'order_confirmation',
  bypass_preferences: true,  // Send even if opted out of marketing
  data: { order_id: 'ord_123' }
});

// Marketing: Check preferences first
if (user.subscribed_to_promotions && user.preferences_email) {
  sendEmail({
    to: user.email,
    template: 'weekly_deals',
    respect_preferences: true,
    data: { deals: [...] }
  });
}

Default Preferences (What If User Hasn’t Set Any?)

Recommended Defaults

Conservative approach (better for compliance):

// Default user to opted OUT of marketing, IN for transactional
const defaultPreferences = {
  subscribed_to_promotions: false,       // Opt-in required
  subscribed_to_newsletter: false,       // Opt-in required
  subscribed_to_product_updates: false,  // Opt-in required
  subscribed_to_transactional: true,     // Always on
  
  preferences_email: true,               // Email enabled (but only transactional)
  preferences_push: false,               // Opt-in required
  preferences_sms: false                 // Opt-in required
};

Aggressive approach (better for engagement, riskier legally):

// Default user to opted IN to everything
const defaultPreferences = {
  subscribed_to_promotions: true,    // Opt-out to stop
  subscribed_to_newsletter: true,    // Opt-out to stop
  subscribed_to_product_updates: true,
  subscribed_to_transactional: true,
  
  preferences_email: true,
  preferences_push: true,            // Requires device token
  preferences_sms: false             // SMS usually requires explicit opt-in
};

When to use each:

Conservative: EU users (GDPR), healthcare, financial services
Aggressive: Existing customers, B2B, low-regulation industries

Preference Syncing Across Devices

Challenge: User opts out of push notifications on phone, but still gets them on tablet. Solution: Preferences are stored at the user profile level, not device level. How it works:

// User opts out on iPhone
Zixflow.setProfileAttributes({
  preferences_push: false  // Applies to ALL devices
});

// Next campaign:
// → iPhone: No push (opted out)
// → iPad: No push (opted out)
// → Web: No push (opted out)

Device-specific preferences (if needed):

// Opt out on THIS device only
Zixflow.setDeviceAttributes({
  push_enabled: false  // Only this device
});

Compliance & Legal Requirements

Requirements: ✅ Clear consent before marketing communications
✅ Easy way to withdraw consent (unsubscribe link)
✅ Granular control (not just “all or nothing”)
✅ Explicit opt-in for sensitive categories (health, finance) Implementation:

Default users to opted OUT
Require checkbox during signup: “I agree to receive marketing emails”
Provide preference center with granular controls

CAN-SPAM (United States)

Requirements: ✅ Unsubscribe link in every marketing email
✅ Honor opt-out within 10 business days
✅ Clear “From” name (not deceptive)
✅ Accurate subject line Implementation:

Include unsubscribe link in email footer
Immediately set subscribed_to_promotions = false on click
Exclude opted-out users from all marketing campaigns

CCPA (California)

Requirements: ✅ Allow users to opt out of data “sale” (sharing for advertising)
✅ Provide “Do Not Sell My Personal Information” link
✅ Honor opt-out immediately Implementation:

// User clicks "Do Not Sell"
Zixflow.setProfileAttributes({
  ccpa_opt_out: true,  // Don't share data with ad platforms
  opted_out_at: new Date().toISOString()
});

Next: Server-side tracking and lifecycle APIs → Event API Reference

​What Are User Preferences?

​Why Preferences Matter

​Types of Preferences

​1. Channel Preferences (What to Reach Them On)

​2. Category Preferences (What Type of Messages)

​3. Frequency Preferences (How Often to Message)

​4. User Suppression (Block All Channels)

​Capturing Preferences

​Method 1: In-App Preference Center

​Method 2: Email Unsubscribe Links

​Method 3: Onboarding Preference Collection

​Respecting Preferences in Campaigns

​Transactional vs. Marketing Messages

​Default Preferences (What If User Hasn’t Set Any?)

​Recommended Defaults

​Preference Syncing Across Devices

​Compliance & Legal Requirements

​GDPR (Europe)

​CAN-SPAM (United States)

​CCPA (California)

What Are User Preferences?

Why Preferences Matter

Types of Preferences

1. Channel Preferences (What to Reach Them On)

2. Category Preferences (What Type of Messages)

3. Frequency Preferences (How Often to Message)

4. User Suppression (Block All Channels)

Capturing Preferences

Method 1: In-App Preference Center

Method 2: Email Unsubscribe Links

Method 3: Onboarding Preference Collection

Respecting Preferences in Campaigns

Transactional vs. Marketing Messages

Default Preferences (What If User Hasn’t Set Any?)

Recommended Defaults

Preference Syncing Across Devices

Compliance & Legal Requirements

GDPR (Europe)

CAN-SPAM (United States)

CCPA (California)