Subscribers

Subscribers are the recipients of your notifications across all channels. You can manage subscribers through the Dashboard or the API.

Creating Subscribers

Via Dashboard

1. Navigate to Subscribers in the sidebar
2. Click Create Subscriber
3. Fill in the subscriber details (email, phone, name, external ID)
4. Optionally add custom metadata as key-value pairs
5. Click Create

Via API

curl -X POST https://api.zyphr.dev/v1/subscribers \
  -H "X-API-Key: zy_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "user_123",
    "email": "user@example.com",
    "phone": "+14155551234",
    "name": "John Doe",
    "metadata": {
      "plan": "pro",
      "signup_date": "2024-01-15"
    }
  }'

const subscriber = await zyphr.subscribers.create({
  externalId: 'user_123',  // Your user ID
  email: 'user@example.com',
  phone: '+14155551234',
  name: 'John Doe',
  metadata: {
    plan: 'pro',
    signupDate: '2024-01-15',
  },
});

Upsert Behavior

The create endpoint uses upsert logic — if a subscriber with the same external_id already exists, it will be updated instead of creating a duplicate.

Subscriber Fields

Field	Description
externalId	Your unique user identifier
email	Email address
phone	Phone number (E.164 format)
name	Display name
metadata	Custom key-value data
preferences	Channel and category preferences

Viewing Subscribers

Via Dashboard

1. Navigate to Subscribers in the sidebar
2. Browse the subscriber list with search and pagination
3. Click on any subscriber to view their full profile, preferences, and message history

Via API

# List subscribers
curl "https://api.zyphr.dev/v1/subscribers?page=1&per_page=25" \
  -H "X-API-Key: zy_live_your_key"

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

# Get by external ID
curl https://api.zyphr.dev/v1/subscribers/external/user_123 \
  -H "X-API-Key: zy_live_your_key"

Updating Subscribers

Via Dashboard

1. Navigate to Subscribers and click on a subscriber
2. Edit their details (name, email, phone, metadata)
3. Click Save

Via API

curl -X PATCH https://api.zyphr.dev/v1/subscribers/user_123 \
  -H "X-API-Key: zy_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John D.",
    "metadata": { "plan": "enterprise" }
  }'

Deleting Subscribers

Via Dashboard

1. Navigate to Subscribers and click on a subscriber
2. Click Delete Subscriber
3. Confirm the deletion

Via API

curl -X DELETE https://api.zyphr.dev/v1/subscribers/user_123 \
  -H "X-API-Key: zy_live_your_key"

Managing Preferences

Subscribers can control their notification preferences at the channel and category level.

Via Dashboard

1. Navigate to Subscribers and click on a subscriber
2. Go to the Preferences tab
3. Toggle channels (email, push, SMS, in-app) on or off
4. Enable or disable specific notification categories per channel

Via API

curl -X PUT 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 },
});

Get Preferences

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

See Subscriber Preferences for more details on building preference centers.

Notification Categories

Define categories to let subscribers choose which types of notifications they receive.

Via Dashboard

1. Navigate to Subscribers in the sidebar
2. Click on the Categories tab
3. Click Create Category
4. Enter a name and slug (e.g., "Marketing Updates" / marketing)
5. Categories become available for subscribers to enable/disable

Via API

# Create a 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 categories
curl https://api.zyphr.dev/v1/subscribers/categories \
  -H "X-API-Key: zy_live_your_key"