Core Concepts
Zyphr is built around a small set of primitives that work together to power your notification infrastructure.
Accounts, Projects, and Applications
Everything in Zyphr lives inside a container hierarchy. It determines which credentials you present and which configuration a send resolves.
account your organization; billing lives here
└── project an isolated environment — its own subscribers, devices,
│ templates and secret API keys (zy_live_* / zy_test_*)
└── application an app within the project, with its own credentials (za_*)
└── environment test | live
| Level | What it owns | Credential |
|---|---|---|
| Account | Billing, team members, domains | Dashboard login |
| Project | Subscribers, devices, templates, provider configs | zy_live_* / zy_test_* secret API keys |
| Application | Auth-as-a-Service apps; per-app push provider configs | za_pub_* (legacy, application-level) |
| Environment | Per-environment provider configs and credentials | za_test_pub_* / za_live_pub_* |
Most integrations only need account → project. A single project with your secret API key covers subscribers, templates, and push. Applications matter when you use Auth-as-a-Service, or when you ship several apps that each need their own push credentials.
Provider configurations may be attached at any level. At send time Zyphr resolves the most specific configuration available: environment → application → project.
Subscribers and devices belong to a project. external_id is unique per project, and push delivery targets every device registered under a user_id within the project.
Applications scope which provider credentials deliver a notification — they do not create separate subscriber namespaces, and they do not filter delivery. If you need genuinely isolated apps, use a separate project per app.
See Scoping devices to an application for what this means in practice.
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.