How the Comment Notification Digest Batches Client Activity Into One Email

If a client leaves several comments on a shared invoice within a short window, you get exactly one email about it — not one email per comment. That's the comment notification digest at work: a small batching system that deliberately waits before sending, and resets its own timer every time a new comment comes in, so a burst of client activity collapses into a single, accurate summary email instead of flooding your inbox.

The Core Mechanism: Delay, Then Reset on Every New Comment

When a client leaves a comment on a shared invoice, the system doesn't send an email immediately. Instead, it schedules one for a short delay later — five minutes by default. If a second comment comes in from that same client conversation before the five minutes are up, the system doesn't schedule a second, separate email. It finds the still-pending digest for that same recipient and invoice, and updates it: the comment count increments, the "latest message" field is overwritten with the newest comment's text, and — critically — the scheduled send time is pushed back out to five minutes from *this* new comment, not the original one.

This reset-on-activity behavior means the email only actually goes out once the conversation has been quiet for a full five minutes. If a client leaves four comments spaced two minutes apart, no email fires until five minutes after that fourth and final comment — at which point you get a single email reporting all four, not four separate emails arriving throughout the conversation. Only once the digest is actually sent does the count get closed out; any further comments after that point start a fresh new digest cycle.

Why a Rolling Delay Instead of a Fixed One

A simpler design would batch comments into fixed windows — say, one digest email every five minutes, whatever came in during that window. The rolling reset is a deliberate improvement on that: it's tuned to actually catch the end of a conversation rather than an arbitrary clock tick. If a client is actively working through several points on an invoice in a back-and-forth burst, a fixed five-minute window might cut that conversation in half and send you an incomplete digest partway through, followed by a second one moments later. Resetting the timer on every new comment means the email genuinely waits until the client has stopped, so what you receive is the complete, final state of that conversation, not a partial snapshot from wherever an arbitrary clock happened to land.

What the Digest Email Actually Contains

When the digest finally sends, it includes the client's name, the document number it relates to, the document type, the total comment count accumulated during that window, and the text of the single most recent comment — not a full transcript of every comment in the burst. This is a deliberate simplification: the email is meant to tell you that activity happened and roughly how much, prompting you to go open the actual comment thread in the dashboard for the full conversation, rather than trying to reproduce the entire thread inline in an email body. The count is what tells you "four comments came in," and the latest message gives you a preview of where the conversation currently stands, without needing to read the earlier ones in the email itself to know it's worth checking.

The Background Worker That Actually Sends Them

A background process checks every thirty seconds for any digest whose scheduled send time has arrived and hasn't gone out yet, pulling up to twenty-five due digests per pass and sending each one in turn. Thirty seconds is frequent enough that the actual delay you experience closely matches the intended five-minute window — you're not waiting extra time for a slow-polling worker to notice a digest is ready. Each digest is marked as sent immediately after a successful send, guarded so the same digest can't be picked up and sent twice even if the worker's check overlaps with another pass.

What Happens If Sending Fails

If sending a specific digest email fails — a mail-provider issue, a malformed recipient address — the error is logged, and that one digest is simply left unsent for now rather than marking it as sent or crashing the whole batch. Every other due digest in that same worker pass is still attempted independently; one failure doesn't block the rest. The failed digest will still be picked up and retried on the worker's next thirty-second pass, since it remains in the "not yet sent" state until a send actually succeeds.

This Can Be Turned Off Entirely

If outbound mail is disabled at the environment level — a setting used in testing or in specific deployment configurations — the entire digest system no-ops at both ends: new comments don't get queued into a pending digest in the first place, and the background worker that would send them never starts running. This avoids doing pointless bookkeeping work queuing up digests that could never actually be delivered anyway.

Why This Design Matters More Than It Looks

Notification batching sounds like a minor quality-of-life detail, but the alternative — a real-time email for every single comment — is one of the more common reasons people quietly disable notifications for a feature altogether and stop noticing genuinely important activity buried in a flood of low-value alerts. A five-minute, activity-aware delay is short enough that you're still finding out about client feedback essentially in real time from a practical standpoint, but long enough to absorb a natural back-and-forth burst into the single email it actually deserves — which is the difference between a notification system people keep enabled and trust, and one they eventually mute.

How This Differs From the In-App Notification

It's worth being clear that this digest system is specifically about the email side of comment notifications — the in-app notification bell operates on entirely separate, immediate logic, generating a notification row for every active workspace member the moment a comment is posted, with no delay and no batching. The two exist for different contexts: the in-app notification is built for someone actively working in the dashboard who benefits from immediate visibility, while the email digest is built for reaching someone who isn't currently looking at the product, where a five-minute, activity-aware delay does far more good than harm. A team member who has the dashboard open will typically see the in-app notification well before any digest email would have fired at all; the digest exists specifically for the times nobody's watching in real time.

A Worked Timeline Example

Say a client opens a shared invoice and leaves a comment at 2:00pm. A digest is scheduled for 2:05pm, with a comment count of one. At 2:03pm, the same client leaves a second comment, clarifying their first point. The system finds the still-pending 2:05pm digest, bumps the comment count to two, replaces the stored "latest message" with this second comment's text, and pushes the scheduled send time out to 2:08pm. No further comments arrive. At 2:08pm, the next thirty-second worker pass finds the digest due, and sends a single email reporting two comments, with the second comment's text as the preview — a complete, accurate summary of an eight-minute conversation, delivered as one message roughly five minutes after the client actually stopped typing, rather than two separate emails arriving three minutes apart mid-conversation.

The Delay Window Is Configurable at the Environment Level

The five-minute default delay isn't hardcoded as an unchangeable constant — it's read from an environment variable at startup, falling back to five minutes only if that variable isn't set or isn't a valid number. This means the delay can be tuned differently across environments without touching any code: a shorter delay for a testing environment where you want to verify digest behavior quickly, or a longer one in production if a particular deployment decides a longer quiet-period better fits how its clients tend to leave comments. Whatever the configured value, the reset-on-new-comment behavior works identically regardless of how long the window is set to — only the length of the quiet period needed before a send actually fires changes.

The thirty-second background worker interval is separate from that delay setting and isn't currently exposed as its own configurable value — it's tuned to be short enough that it never meaningfully adds to the perceived delay, since thirty seconds is a small fraction of even the shortest sensible digest window. In practice this means the actual time between "a conversation goes quiet" and "the digest email lands in your inbox" is, for all realistic purposes, just the configured delay itself, with the worker's polling interval contributing at most a few extra seconds on top.