Skip to main content

Subscriber Preferences

Give users control over which notifications they receive. Preferences can be managed through the Dashboard, the API, or an embeddable React component.

Preference Levels​

  1. Global - Enable/disable all notifications
  2. Channel - Enable/disable by channel (email, push, SMS, in-app)
  3. Category - Enable/disable by category (marketing, updates, etc.)

Managing Notification Categories​

Before subscribers can set preferences per category, you need to define your notification categories.

Via Dashboard​

  1. Navigate to Subscribers in the sidebar
  2. Click on the Categories tab
  3. Click Create Category
  4. Enter a name, slug, and description
  5. Click Create

Via API​

# Create a notification category
curl -X POST https://api.zyphr.dev/v1/subscribers/categories \
  -H "X-API-Key: zy_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Updates",
    "slug": "marketing",
    "description": "Product announcements and promotional content"
  }'

# List all categories
curl https://api.zyphr.dev/v1/subscribers/categories \
  -H "X-API-Key: zy_live_your_key"

# Update a category
curl -X PATCH https://api.zyphr.dev/v1/subscribers/categories/CATEGORY_ID \
  -H "X-API-Key: zy_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Product Updates" }'

# Delete a category
curl -X DELETE https://api.zyphr.dev/v1/subscribers/categories/CATEGORY_ID \
  -H "X-API-Key: zy_live_your_key"

Setting Preferences​

Via Dashboard​

  1. Navigate to Subscribers and click on a subscriber
  2. Go to the Preferences tab
  3. Toggle channels on/off (email, push, SMS, in-app)
  4. Expand each channel to enable/disable specific categories
  5. Changes save automatically

Via API​

curl -X POST https://api.zyphr.dev/v1/subscribers/sub_abc/preferences \
  -H "X-API-Key: zy_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": {
      "enabled": true,
      "categories": {
        "marketing": false,
        "transactional": true
      }
    },
    "push": { "enabled": true },
    "sms": { "enabled": false },
    "in_app": { "enabled": true }
  }'
await zyphr.subscribers.updatePreferences('sub_abc', {
  email: {
    enabled: true,
    categories: {
      marketing: false,
      transactional: true,
    },
  },
  push: { enabled: true },
  sms: { enabled: false },
  inApp: { enabled: true },
});

Via React Component​

Use the pre-built preference center component for your end users:

import { ZyphrPreferences } from '@zyphr/inbox-react';

<ZyphrPreferences
  categories={[
    { id: 'social', label: 'Social Updates' },
    { id: 'billing', label: 'Billing & Payments' },
    { id: 'product', label: 'Product Updates' },
  ]}
/>

Getting Preferences​

Via Dashboard​

Navigate to Subscribers, click a subscriber, and view the Preferences tab.

Via API​

# Get subscriber preferences
curl https://api.zyphr.dev/v1/subscribers/sub_abc/preferences \
  -H "X-API-Key: zy_live_your_key"

# Get effective preferences (merged with defaults)
curl https://api.zyphr.dev/v1/subscribers/sub_abc/preferences/effective \
  -H "X-API-Key: zy_live_your_key"
const prefs = await zyphr.subscribers.getPreferences('sub_abc');

Honoring Preferences​

Preferences are automatically respected when sending notifications:

// This will be blocked if the subscriber disabled push
await zyphr.push.send({
  subscriberId: 'sub_abc',
  title: 'Update',
  body: 'New features!',
});

To bypass preferences for critical notifications (e.g., security alerts, password resets), use the force flag or mark the workflow as critical:

// Force delivery regardless of preferences
await zyphr.emails.send({
  to: 'user@example.com',
  subject: 'Security Alert',
  html: '<p>Unusual login detected...</p>',
  force: true,
});

Unsubscribe and Resubscribe​

Via API​

# Unsubscribe from a category on a channel
curl -X POST https://api.zyphr.dev/v1/subscribers/sub_abc/unsubscribe \
  -H "X-API-Key: zy_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "category": "marketing"
  }'

# Resubscribe
curl -X POST https://api.zyphr.dev/v1/subscribers/sub_abc/resubscribe \
  -H "X-API-Key: zy_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "category": "marketing"
  }'

# View unsubscribe history
curl https://api.zyphr.dev/v1/subscribers/sub_abc/unsubscribes \
  -H "X-API-Key: zy_live_your_key"

Track and manage subscriber consent for compliance:

# Record consent
curl -X POST https://api.zyphr.dev/v1/subscribers/sub_abc/consent/record \
  -H "X-API-Key: zy_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "source": "signup_form",
    "ip_address": "203.0.113.42"
  }'

# Check consent status
curl https://api.zyphr.dev/v1/subscribers/sub_abc/consent/status \
  -H "X-API-Key: zy_live_your_key"

# View consent history
curl https://api.zyphr.dev/v1/subscribers/sub_abc/consent/history \
  -H "X-API-Key: zy_live_your_key"