Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

fix(emails): limit inactivity alerts to once per owner per week (#1299)

Goldflagb8447ce745b8
diff --git a/server/src/services/lifecycleEmails/lifecycleContent.ts b/server/src/services/lifecycleEmails/lifecycleContent.ts
index 670afb237..a557d8c28 100644
--- a/server/src/services/lifecycleEmails/lifecycleContent.ts
+++ b/server/src/services/lifecycleEmails/lifecycleContent.ts
@@ -288,9 +288,9 @@ export const wentQuiet = (sitesIn: QuietSite[], name?: string | null): Lifecycle
subject: `We stopped hearing from ${domain}`,
text: `${greeting(name)}
-${domain} was sending data to Rybbit, but we haven't received anything since ${lastEventAt}. If you redeployed recently, the tracking snippet may have been dropped from the new build - that's the usual cause.
+${domain} was sending data to Rybbit, but we haven't received anything since ${lastEventAt}.
-Check that the snippet is still in your <head>, or see your dashboard: ${appUrl()}/${siteId}
+A quiet period can be normal if your site has fewer visits. If you expected traffic, check that the tracking snippet is still loading on your site, or see your dashboard: ${appUrl()}/${siteId}
If you removed it on purpose, ignore this - I won't email about it again.${signoff}`,
};
@@ -308,7 +308,7 @@ ${sitesIn.length} of your sites were sending data to Rybbit, but we haven't rece
${listed}${overflowLine(sitesIn.length, "site")}
-If you redeployed recently, the tracking snippet may have been dropped from the new build - that's the usual cause. Check that the snippet is still in each site's <head>.
+A quiet period can be normal for sites with fewer visits. If you expected traffic, check that the tracking snippet is still loading on each site.
If you removed it on purpose, ignore this - I won't email about these sites again.${signoff}`,
};
diff --git a/server/src/services/lifecycleEmails/lifecycleEmailService.test.ts b/server/src/services/lifecycleEmails/lifecycleEmailService.test.ts
index 576ac4413..cd0803658 100644
--- a/server/src/services/lifecycleEmails/lifecycleEmailService.test.ts
+++ b/server/src/services/lifecycleEmails/lifecycleEmailService.test.ts
@@ -1,5 +1,5 @@
import { DateTime } from "luxon";
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
/**
* The lifecycle cron is a state machine: every email is triggered by a state
@@ -22,7 +22,7 @@ const state = vi.hoisted(() => ({
organizationId: string;
detectedPlatform: string | null;
}>,
- logs: [] as Array<{ userId: string; emailKey: string; sentAt: string }>,
+ logs: [] as Array<{ userId: string; emailKey: string; siteId?: number | null; sentAt: string }>,
recentQuietLogs: [] as Array<{ siteId: number; userId: string; sentAt: string }>,
goals: [] as Array<{ siteId: number }>,
owners: [] as Array<{ organizationId: string; userId: string; email: string; name: string }>,
@@ -70,7 +70,17 @@ vi.mock("../../db/postgres/postgres.js", () => {
// Reads are told apart by the columns each one selects.
select: (fields: Record<string, unknown>) =>
chain(() => {
- if ("siteId" in fields && "userId" in fields && "sentAt" in fields) return state.recentQuietLogs;
+ if ("siteId" in fields && "userId" in fields && "sentAt" in fields) {
+ return [
+ ...state.recentQuietLogs,
+ ...state.logs.filter(
+ l =>
+ l.emailKey.startsWith("went_quiet:") &&
+ l.siteId != null &&
+ DateTime.fromISO(l.sentAt) > now().minus({ days: 30 })
+ ),
+ ];
+ }
if ("emailKey" in fields && "userId" in fields) return state.logs;
if ("role" in fields) return state.memberships;
if ("createdAt" in fields && "email" in fields) return state.users;
@@ -80,7 +90,7 @@ vi.mock("../../db/postgres/postgres.js", () => {
return state.goals;
}),
insert: () => ({
- values: (rows: Array<{ userId: string; emailKey: string }>) => ({
+ values: (rows: Array<{ userId: string; emailKey: string; siteId: number | null }>) => ({
onConflictDoNothing: () => ({
returning: async () => {
const claimed: string[] = [];
@@ -90,7 +100,7 @@ vi.mock("../../db/postgres/postgres.js", () => {
if (state.sentKeys.has(key)) continue; // unique-index conflict
state.sentKeys.add(key);
// Mirror the real table: the row is now visible to later reads
- state.logs.push({ userId: row.userId, emailKey: row.emailKey, sentAt: new Date().toISOString() });
+ state.logs.push({ ...row, sentAt: new Date().toISOString() });
claimed.push(key);
returned.push({ id: state.sentKeys.size, emailKey: row.emailKey });
}
@@ -126,14 +136,23 @@ vi.mock("../../db/postgres/postgres.js", () => {
vi.mock("../../db/clickhouse/clickhouse.js", () => ({
clickhouse: {
- query: async ({ query }: { query: string }) => {
+ query: async ({ query, query_params }: { query: string; query_params?: Record<string, unknown> }) => {
const rows = (() => {
if (query.includes("custom_events")) return state.siteStats;
if (query.includes("ORDER BY timestamp ASC")) return state.firstPageview;
if (query.includes("uniq(session_id)")) return state.overview;
if (query.includes("GROUP BY value")) return state.topRows;
if (query.includes("INTERVAL 14 DAY")) return state.convertingPaths;
- if (query.includes("HAVING last_event")) return state.quietCandidates;
+ if (query.includes("HAVING last_event")) {
+ // Apply the candidate window so a deferred site can age out, just as
+ // it would in ClickHouse.
+ const windowStart = DateTime.fromSeconds(Number(query_params?.windowStart));
+ const quietBefore = DateTime.fromSeconds(Number(query_params?.quietBefore));
+ return state.quietCandidates.filter(row => {
+ const lastEvent = DateTime.fromSQL(row.last_event, { zone: "utc" });
+ return lastEvent > windowStart && lastEvent < quietBefore;
+ });
+ }
if (query.includes("INTERVAL 21 DAY")) return state.establishedSites;
return [];
})();
@@ -189,6 +208,10 @@ beforeEach(() => {
(lifecycleEmailService as any).negativeCache.clear();
});
+afterEach(() => {
+ vi.useRealTimers();
+});
+
describe("state: signed up, no site", () => {
it("sends the finish-setup email once the 2h timeout passes", async () => {
addUser("u1", hoursAgo(3));
@@ -403,6 +426,11 @@ describe("state: data flowing", () => {
});
describe("state: went quiet", () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date("2026-10-07T12:00:00Z"));
+ });
+
const quietSite = () => {
state.quietCandidates.push({ site_id: 7, last_event: hoursAgo(50) });
state.establishedSites.push({ site_id: 7, total: 5000 });
@@ -449,19 +477,63 @@ describe("state: went quiet", () => {
expect(state.logs.map(l => l.emailKey).filter(k => k.startsWith("went_quiet:")).length).toBe(2);
});
- it("waits 24h after an owner's last went-quiet email before alerting about another site", async () => {
+ it.each([25, 6 * 24, 7 * 24 - 1 / 60])(
+ "holds another site's alert when the owner's previous email is %s hours old",
+ async lastSentHours => {
+ quietSite();
+ state.recentQuietLogs.push({ siteId: 99, userId: "owner1", sentAt: hoursAgo(lastSentHours) });
+ await run();
+ expect(mocks.sendLifecycleEmail).not.toHaveBeenCalled();
+ expect(state.logs).toHaveLength(0);
+ }
+ );
+
+ it("allows another site's alert exactly seven days after the owner's previous email", async () => {
quietSite();
- // A different site of the same owner was reported 3 hours ago
- state.recentQuietLogs.push({ siteId: 99, userId: "owner1", sentAt: hoursAgo(3) });
+ state.recentQuietLogs.push({ siteId: 99, userId: "owner1", sentAt: daysAgo(7) });
+ await run();
+ expect(sentSubjects()).toEqual(["We stopped hearing from quiet.com"]);
+ });
+
+ it("bundles sites that stayed quiet during the weekly cooldown, including sites in another organization", async () => {
+ quietSite();
+ await run();
+
+ // The next day, two more sites become eligible for the same owner.
+ vi.setSystemTime(new Date("2026-10-08T12:00:00Z"));
+ for (const [siteId, domain, organizationId] of [
+ [8, "quiet2.com", "org-x"],
+ [9, "quiet3.com", "org-y"],
+ ] as const) {
+ state.quietCandidates.push({ site_id: siteId, last_event: hoursAgo(50) });
+ state.establishedSites.push({ site_id: siteId, total: 3000 });
+ state.sites.push({ siteId, domain, createdAt: daysAgo(200), organizationId, detectedPlatform: null });
+ }
+ state.owners.push({ organizationId: "org-y", userId: "owner1", email: "[email protected]", name: "Ada" });
+ await run();
+ expect(mocks.sendLifecycleEmail).toHaveBeenCalledTimes(1);
+
+ // At the weekly boundary, those sites have had no events for over eight
+ // days. They must remain candidates and share one message.
+ vi.setSystemTime(new Date("2026-10-14T12:00:00Z"));
+ await run();
+ expect(sentSubjects()).toEqual([
+ "We stopped hearing from quiet.com",
+ "We stopped hearing from quiet2.com and 1 other site",
+ ]);
+ expect(state.logs.filter(l => l.emailKey.startsWith("went_quiet:")).map(l => l.siteId)).toEqual([7, 8, 9]);
+ });
+
+ it("does not alert about a deferred site that resumed sending events before the cooldown ended", async () => {
+ quietSite();
+ state.recentQuietLogs.push({ siteId: 99, userId: "owner1", sentAt: daysAgo(6) });
await run();
expect(mocks.sendLifecycleEmail).not.toHaveBeenCalled();
- // Once the day has passed, the held site is reported
- state.recentQuietLogs.length = 0;
- state.recentQuietLogs.push({ siteId: 99, userId: "owner1", sentAt: hoursAgo(25) });
- (lifecycleEmailService as any).lastWentQuietAt = null;
+ vi.setSystemTime(new Date("2026-10-08T12:00:00Z"));
+ state.quietCandidates[0].last_event = hoursAgo(1);
await run();
- expect(sentSubjects()).toEqual(["We stopped hearing from quiet.com"]);
+ expect(mocks.sendLifecycleEmail).not.toHaveBeenCalled();
});
});
diff --git a/server/src/services/lifecycleEmails/lifecycleEmailService.ts b/server/src/services/lifecycleEmails/lifecycleEmailService.ts
index 1aa6ccdfe..813bda4d9 100644
--- a/server/src/services/lifecycleEmails/lifecycleEmailService.ts
+++ b/server/src/services/lifecycleEmails/lifecycleEmailService.ts
@@ -21,9 +21,9 @@ import { detectPlatform, platformForKey, type PlatformInfo } from "./platformDet
*
* Per-site emails (install track, "you're live", went quiet) are evaluated per
* site but sent per user: every site eligible in the same run is bundled into
- * one message, and each kind is sent to a user at most once per
- * KIND_COOLDOWN_HOURS. An agency that adds 13 domains gets one snippet email
- * listing 13 snippets, not 13 emails ten minutes apart.
+ * one message. Install and live emails have a 24-hour per-kind cooldown;
+ * went-quiet emails have a seven-day per-user cooldown. An agency that adds
+ * 13 domains gets one snippet email listing 13 snippets.
*
* Concurrency: the cron runs on the cluster primary only, so a single
* evaluator holds the "one email per user per run" invariant. If this ever
@@ -33,7 +33,9 @@ import { detectPlatform, platformForKey, type PlatformInfo } from "./platformDet
const COHORT_DAYS = 30; // users/sites older than this never enter the onboarding flow
const MIN_GAP_HOURS = 48; // between non-transition emails to the same user
-const KIND_COOLDOWN_HOURS = 24; // between two emails of the same per-site kind to the same user
+const KIND_COOLDOWN_HOURS = 24; // between install/live emails of the same kind to the same user
+const WENT_QUIET_COOLDOWN_DAYS = 7;
+const WENT_QUIET_LOOKBACK_DAYS = 14; // covers the 48h silence threshold plus a full weekly cooldown
const CHECK_INSTALL_TTL_SECONDS = 30 * 24 * 3600;
const NEGATIVE_CACHE_TTL_MS = 12 * 3600 * 1000; // don't re-run a no-result ClickHouse probe for this long
@@ -604,19 +606,22 @@ class LifecycleEmailService {
// -------------------------------------------------------------------------
private async processWentQuiet(now: DateTime): Promise<void> {
- // Candidates: sites with events in the last 7 days whose latest event is
- // older than 48h. The 7-day window (vs a hard 48-60h band) means a cron
- // outage longer than the band can't silently skip an alert; the per-outage
- // email key plus the 30-day per-site cooldown below prevent repeats.
+ // Keep candidates for two weeks so a site that becomes quiet during its
+ // owner's weekly cooldown can still join the next bundle. Evaluate the
+ // window against this run's clock and re-check silence before sending.
const result = await clickhouse.query({
query: `
SELECT site_id, max(timestamp) AS last_event
FROM events
- WHERE timestamp > now() - INTERVAL 7 DAY
+ WHERE timestamp > toDateTime({windowStart:UInt32}, 'UTC')
GROUP BY site_id
- HAVING last_event < now() - INTERVAL 48 HOUR
+ HAVING last_event < toDateTime({quietBefore:UInt32}, 'UTC')
`,
format: "JSONEachRow",
+ query_params: {
+ windowStart: Math.floor(now.minus({ days: WENT_QUIET_LOOKBACK_DAYS }).toSeconds()),
+ quietBefore: Math.floor(now.minus({ hours: 48 }).toSeconds()),
+ },
});
const quietRows = await result.json<{ site_id: number; last_event: string }>();
if (quietRows.length === 0) return;
@@ -681,8 +686,8 @@ class LifecycleEmailService {
const ownerByOrg = new Map(owners.map(o => [o.organizationId, o]));
const lastEventBySite = new Map(quietRows.map(r => [Number(r.site_id), parseTs(r.last_event)]));
- // Group by owner: an agency with eight quiet sites gets one email listing
- // eight sites, at most once per KIND_COOLDOWN_HOURS.
+ // Group across the owner's organizations: all eligible quiet sites share
+ // one email, at most once every seven days.
const quietByOwner = new Map<string, { owner: (typeof owners)[number]; sites: typeof quietSites }>();
for (const site of quietSites) {
if (recentlyAlerted.has(site.siteId)) continue;
@@ -698,7 +703,7 @@ class LifecycleEmailService {
// an onboarding email waits for the next tick.
if (this.emailedThisRun.has(owner.userId)) continue;
const lastQuiet = lastQuietEmailByUser.get(owner.userId) ?? null;
- if (lastQuiet && now.diff(lastQuiet, "hours").hours < KIND_COOLDOWN_HOURS) continue;
+ if (lastQuiet && now.diff(lastQuiet, "hours").hours < WENT_QUIET_COOLDOWN_DAYS * 24) continue;
try {
if (await isContactUnsubscribed(owner.email)) continue;
// Per-outage key: the date of the last event identifies the outage, so
@@ -736,7 +741,7 @@ class LifecycleEmailService {
const now = DateTime.utc();
try {
await this.processOnboarding(now);
- // The went-quiet scan covers the whole events table (bounded to 7 days);
+ // The went-quiet scan covers the whole events table (bounded to 14 days);
// hourly is plenty for a 48h-silence alert.
if (!this.lastWentQuietAt || now.diff(this.lastWentQuietAt, "minutes").minutes >= 55) {
this.lastWentQuietAt = now;