Notify guides
21 · Batching and digests

12 new comments, not 12 emails.

Batch a notification type over a window, or into a daily or weekly digest in each recipient's time zone. You keep sending one notification per event.

Batching is a setting on the notification type. Sends don't change: each comment, like or mention is still one notifications.send, and Notify collects them per recipient (and per key, such as the post) until the batch closes.


1

A window

The batch closes window_seconds after its first notification. With sliding, every new one restarts the window, so a burst goes out once it is quiet, but never later than max_window_seconds after the first.

batch-window.ts
await notify.notificationTypes.update("0193a8b2-7c1d-7e3f-9a40-5b6c7d8e9f10", {
  batch: {
    mode: "window",
    key: "post_id",          // one batch per post
    window_seconds: 600,     // send 10 minutes after the first comment…
    sliding: true,           // …or after the latest, while they keep coming
    max_window_seconds: 3600,
    max_items: 5,            // batch.items holds the 5 newest
    inbox: "collapse",       // one inbox item per batch, updated live
  },
});

2

A digest

daily, or weekly on a weekday, at a local time: the recipient's time zone, else your workspace default, else UTC.

batch-digest.ts
await notify.notificationTypes.update("0193a8b2-7c1d-7e3f-9a40-5b6c7d8e9f11", {
  batch: { mode: "digest", schedule: { frequency: "daily", time: "09:00" }, inbox: "each" },
});

// Sends don't change: each comment is one call, and the digest collects them.
await notify.notifications.send(
  { type: "comment.digest", recipients: ["user_123"], data: { text: "Lovely post!" }, actor: { name: "Ada" } },
  { idempotencyKey: "comment.digest:c_77" },
);

3

Templates

When the batch closes, every batched channel (email, mobile push, browser push, webhook) sends one message rendered with batch. In a push title: {{batch.latest.actor.name}}{{#batch.has_others}} and {{batch.others_count}} others{{/batch.has_others}} commented. Email templates in Mail get the same object for {{#each batch.items}}.

Batch variables
VariableWhat it is
batch.countNotifications in the batch (all of them).
batch.itemsThe newest max_items, each with its data, actor and created_at.
batch.latest / batch.earliestThe newest and the oldest item.
batch.has_others / batch.others_countFor "Ada and 3 others": more than one item, and how many besides the latest.
batch.actors / batch.actor_countThe distinct actors, newest first, and how many.
batch.more_countItems not listed in batch.items.
batch.keyThe batch key value (the post id).

4

The inbox

The inbox never waits. With inbox: "collapse" (the default) each open batch is one item, replaced, and unread again, as notifications join it, so the bell counts one. With "each" every notification gets its own item.


5

What still applies

  • Preferences, quiet hours, the per-recipient limits and the type's throttle apply when the batch is sent, and count it once.
  • Cancelling a notification takes it out of its batch; a batch whose sends were all cancelled closes as cancelled.
  • Critical types are never batched, and batching works with always routing (no fallback steps). Scheduled sends of a batched type are refused: the batch decides when.
  • The message log shows each delivery as scheduled: batched until its batch closes; then one carries the message and the others are skipped: batched_into, with the batch_id. dry_run and the explain tool say which batch a send would join and when it closes.
batches.ts
for await (const b of notify.batches.list({ recipient: "user_123", state: "open" })) {
  console.log(b.type, b.key, b.item_count, b.flush_at);
}
const closed = await notify.batches.flush("0193a8b2-7c1d-7e3f-9a40-5b6c7d8e9f20");
console.log(closed.batch.payload); // what the templates got as batch.*