Notification Digests

Digests let you batch multiple notifications into a single summary message instead of bombarding users with individual notifications. Configure time-based or count-based windows, and Zyphr automatically collects and delivers them as a digest.

Overview

Instead of sending a notification every time an event occurs, digests accumulate events over a configured window and deliver them as a single message. This is ideal for:

• Activity feeds - "You have 5 new comments" instead of 5 separate emails
• Report summaries - Daily or weekly rollups of activity
• High-frequency events - Batch order updates, log alerts, or social notifications

Quick Start

1. Create a Digest Configuration

curl -X POST https://api.zyphr.dev/v1/digests \
  -H "X-API-Key: zy_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Comment Digest",
    "channel": "email",
    "digest_key": "post_id",
    "batch_window": "1h",
    "template_id": "comment-digest"
  }'

const digest = await zyphr.digests.create({
  name: 'Comment Digest',
  channel: 'email',
  digestKey: 'post_id',
  batchWindow: '1h',
  templateId: 'comment-digest',
});

2. Send Notifications (They'll Be Batched)

When a notification matches a digest config, it's held and batched automatically based on the digest_key and batch_window.

3. View Pending Items

curl "https://api.zyphr.dev/v1/digests/DIGEST_ID/pending?subscriber_id=user_123&digest_key_value=post_456" \
  -H "X-API-Key: zy_live_your_api_key"

Digest Configuration

Create a Digest

curl -X POST https://api.zyphr.dev/v1/digests \
  -H "X-API-Key: zy_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Update Digest",
    "channel": "email",
    "digest_key": "order_id",
    "batch_window": "30m",
    "max_batch_size": 50,
    "template_id": "order-updates-digest",
    "enabled": true
  }'

Configuration Parameters

Parameter	Type	Required	Description
name	string	Yes	Human-readable name for the digest
channel	string	Yes	Target channel: email, push, sms, in_app
digest_key	string	Yes	The field used to group notifications (e.g., post_id, order_id)
batch_window	string	Yes	Time window for batching (e.g., 15m, 1h, 24h)
max_batch_size	number	No	Maximum items before auto-flush (count-based trigger)
template_id	string	No	Template to use for the digest message
enabled	boolean	No	Whether the digest is active (default: true)

Batch Window Formats

Format	Example	Description
Minutes	15m	Flush every 15 minutes
Hours	1h	Flush every hour
Daily	24h	Flush once per day

note

When both batch_window and max_batch_size are set, the digest flushes when either condition is met — whichever comes first.

List Digest Configurations

curl "https://api.zyphr.dev/v1/digests?channel=email&enabled=true&limit=25" \
  -H "X-API-Key: zy_live_your_api_key"

Query Parameters

Parameter	Type	Description
channel	string	Filter by channel
enabled	boolean	Filter by enabled/disabled
limit	number	Results per page (default: 25, max: 100)
offset	number	Pagination offset

Update a Digest

curl -X PATCH https://api.zyphr.dev/v1/digests/DIGEST_ID \
  -H "X-API-Key: zy_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_window": "2h",
    "max_batch_size": 100
  }'

Delete a Digest

curl -X DELETE https://api.zyphr.dev/v1/digests/DIGEST_ID \
  -H "X-API-Key: zy_live_your_api_key"

warning

Deleting a digest configuration will discard any pending (unbatched) items. Consider disabling instead if you want to preserve pending items.

Manual Flushing

Force-deliver all pending items for a specific subscriber and digest key:

curl -X POST https://api.zyphr.dev/v1/digests/DIGEST_ID/flush \
  -H "X-API-Key: zy_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber_id": "user_123",
    "digest_key_value": "post_456"
  }'

await zyphr.digests.flush(digestId, {
  subscriberId: 'user_123',
  digestKeyValue: 'post_456',
});

This immediately delivers all accumulated items as a digest, regardless of the batch window.

Previewing Pending Items

Check what items are waiting to be batched:

curl "https://api.zyphr.dev/v1/digests/DIGEST_ID/pending?subscriber_id=user_123&digest_key_value=post_456" \
  -H "X-API-Key: zy_live_your_api_key"

Statistics

Get digest performance metrics and recent flush history:

curl https://api.zyphr.dev/v1/digests/DIGEST_ID/stats \
  -H "X-API-Key: zy_live_your_api_key"

Returns:

• Total items batched
• Total flushes (automatic and manual)
• Average batch size
• Recent flush history

Dashboard Management

From the Dashboard:

1. Create digests - Configure new digest rules with batch windows
2. Monitor activity - View pending items and recent flushes
3. Manage configs - Enable/disable, update windows, or delete digests
4. View stats - Track batching efficiency and delivery metrics

Plan Limits

Plan	Max Digest Configs
Free	2
Starter	10
Pro	50
Scale	Unlimited
Enterprise	Unlimited

API Reference

Method	Endpoint	Description
POST	/v1/digests	Create digest configuration
GET	/v1/digests	List digest configs
GET	/v1/digests/:id	Get digest config
PATCH	/v1/digests/:id	Update digest config
DELETE	/v1/digests/:id	Delete digest config
POST	/v1/digests/:id/flush	Manually flush pending items
GET	/v1/digests/:id/stats	Get digest statistics
GET	/v1/digests/:id/pending	Preview pending items

Next Steps

• Scheduled Sending - Schedule messages for future delivery
• Templates - Create digest templates with Handlebars
• Subscriber Preferences - Let users control digest frequency