Core Concepts
Zyphr is built around a small set of primitives that work together to power your notification infrastructure.
The Data Model
Subscribers ──▶ receive notifications via ──▶ Channels (email, push, SMS, in-app, Slack, Discord, Teams)
│ │
│ │
▼ ▼
Preferences Templates
(what they opt into) (reusable content)
│ │
▼ ▼
Topics Digests
(subscriber groups) (batched summaries)
│
▼
Cohorts ──▶ Devices ──▶ Scheduled Messages
(segments) (push tokens) (future delivery)
Subscribers
A subscriber represents a notification recipient — typically a user in your application. Subscribers hold contact information (email, phone), a unique external ID that maps to your user system, and custom metadata.
Every notification Zyphr delivers is sent to a subscriber.
Learn more about Subscribers →
Channels
Channels are the delivery mechanisms for notifications:
| Channel | Use Case |
|---|---|
| Transactional emails, digests, marketing | |
| Push | Real-time mobile and web alerts |
| SMS | Urgent or time-sensitive messages |
| In-App | Persistent notifications within your app |
| Slack | Team channel messages and DMs |
| Discord | Server channel messages with embeds |
| Microsoft Teams | Channel messages with Adaptive Cards |
Each channel has its own configuration, delivery tracking, and status lifecycle.
Templates
Templates are reusable notification content with Handlebars variable interpolation. Define your email layout once, then send it to any subscriber with personalized data.
# Send using a template
curl -X POST https://api.zyphr.dev/v1/emails \
-H "X-API-Key: zy_live_your_key" \
-d '{"to": "user@example.com", "template_id": "welcome", "template_data": {"name": "Jane"}}'
Topics
Topics are subscriber groups that enable fan-out delivery. When you trigger a workflow targeting a topic, every subscriber in that topic receives their own execution — like a pub/sub model for notifications.
Common uses: product announcements, team channels, category subscriptions, regional alerts.
Subscriber Preferences
Preferences give subscribers control over what they receive. Preferences operate at three levels:
- Global — enable/disable all notifications
- Channel — enable/disable by channel (email, push, SMS)
- Category — enable/disable by category (marketing, transactional)
Zyphr automatically respects preferences at delivery time. Notifications marked as is_critical bypass preferences for security-critical messages.
Learn more about Preferences →
How They Work Together
A typical flow:
- A subscriber signs up in your app — you create them in Zyphr
- They subscribe to a topic (e.g., "product-updates")
- You trigger a workflow targeting that topic
- The workflow sends a template through the subscriber's preferred channels
- Delivery respects their preferences — if they disabled push, they get email instead
This composable model lets you start simple (send one email) and scale to complex multi-channel orchestration without changing your architecture.
Additional Primitives
Beyond the core building blocks above, Zyphr provides several advanced primitives:
Digests
Digests batch multiple notifications into periodic summary messages instead of sending each one individually. Configure time-based or count-based windows to control how notifications are grouped.
Cohorts
Cohorts group subscribers into named segments for targeted delivery, performance tracking, and A/B comparisons. Create static cohorts with manual membership, or dynamic cohorts that auto-populate based on filter rules.
Devices
Devices represent push notification endpoints (iOS, Android, Web). Register device tokens to enable targeted push delivery to specific devices or all of a user's devices.
Scheduled Messages
Scheduled messages let you queue notifications for future delivery at a specific time — useful for reminders, drip campaigns, and time-zone-aware sending.