Skip to content

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

fix(lifecycle-emails): bundle per-site emails per user with a 24h cooldown (#1179)

Goldflage5c23c78414d
diff --git a/server/src/services/lifecycleEmails/lifecycleContent.ts b/server/src/services/lifecycleEmails/lifecycleContent.ts
index 3c5c9c8dd..670afb237 100644
--- a/server/src/services/lifecycleEmails/lifecycleContent.ts
+++ b/server/src/services/lifecycleEmails/lifecycleContent.ts
@@ -15,6 +15,25 @@ const greeting = (name?: string | null) => {
const signoff = `\n\nBill\nFounder, Rybbit`;
+/**
+ * Multi-site emails list at most this many sites in the body; the rest are
+ * summarised as a count so an agency onboarding 40 domains gets a readable
+ * email rather than 40 script tags.
+ */
+export const MAX_LISTED_SITES = 10;
+
+/** "acme.com" or "acme.com and 3 other sites" for subjects. */
+export const subjectDomains = (domains: string[]): string => {
+ const others = domains.length - 1;
+ if (others <= 0) return domains[0];
+ return `${domains[0]} and ${others} other site${others === 1 ? "" : "s"}`;
+};
+
+const overflowLine = (total: number, noun: string) => {
+ const hidden = total - MAX_LISTED_SITES;
+ return hidden > 0 ? `\n...and ${hidden} more ${noun}${hidden === 1 ? "" : "s"}.` : "";
+};
+
export const snippetFor = (siteId: number) =>
`<script src="${appUrl()}/api/script.js" data-site-id="${siteId}" defer></script>`;
@@ -48,14 +67,19 @@ This is the last email I'll send unless you start using Rybbit.${signoff}`,
// Stage 2: site created, no data
// ---------------------------------------------------------------------------
-export const installSnippet = (
- domain: string,
- siteId: number,
- platform: PlatformInfo | null,
- name?: string | null
-): LifecycleEmail => ({
- subject: `One step left for ${domain}`,
- text: `${greeting(name)}
+export interface SnippetSite {
+ domain: string;
+ siteId: number;
+ platform: PlatformInfo | null;
+}
+
+export const installSnippet = (sitesIn: SnippetSite[], name?: string | null): LifecycleEmail => {
+ const domains = sitesIn.map(s => s.domain);
+ if (sitesIn.length === 1) {
+ const [{ domain, siteId, platform }] = sitesIn;
+ return {
+ subject: `One step left for ${domain}`,
+ text: `${greeting(name)}
${domain} is set up on Rybbit - it just needs the tracking snippet. Add this to the <head> of every page:
@@ -66,11 +90,39 @@ ${
: `\nUsing a framework or CMS? We have step-by-step guides for most of them:\nhttps://rybbit.com/docs/script\n`
}
As soon as the first pageview arrives you'll see it live on your dashboard. If it's not working after a few minutes, reply and I'll help you debug it.${signoff}`,
-});
+ };
+ }
-export const installCheck = (domain: string, checkInstallUrl: string, name?: string | null): LifecycleEmail => ({
- subject: `Still nothing from ${domain}`,
- text: `${greeting(name)}
+ const listed = sitesIn
+ .slice(0, MAX_LISTED_SITES)
+ .map(s => `${s.domain}${s.platform ? ` (${s.platform.label}: ${s.platform.guideUrl})` : ""}\n${snippetFor(s.siteId)}`)
+ .join("\n\n");
+ return {
+ subject: `One step left for ${subjectDomains(domains)}`,
+ text: `${greeting(name)}
+
+You've added ${sitesIn.length} sites to Rybbit - each one just needs its tracking snippet in the <head> of every page. The snippets differ only by site id:
+
+${listed}${overflowLine(sitesIn.length, "site")}
+
+Every site's snippet is also on its dashboard under Settings. Framework and CMS guides: https://rybbit.com/docs/script
+
+As soon as the first pageview arrives you'll see it live on your dashboard. If something isn't working, reply and I'll help you debug it.${signoff}`,
+ };
+};
+
+export interface CheckSite {
+ domain: string;
+ checkInstallUrl: string;
+}
+
+export const installCheck = (sitesIn: CheckSite[], name?: string | null): LifecycleEmail => {
+ const domains = sitesIn.map(s => s.domain);
+ if (sitesIn.length === 1) {
+ const [{ domain, checkInstallUrl }] = sitesIn;
+ return {
+ subject: `Still nothing from ${domain}`,
+ text: `${greeting(name)}
Your Rybbit snippet hasn't sent any data from ${domain} yet. The three most common causes:
@@ -82,33 +134,89 @@ Click here and we'll fetch ${domain} right now and tell you whether the snippet
${checkInstallUrl}
Stuck? Reply to this email and I'll take a look personally.${signoff}`,
-});
+ };
+ }
-export const installFinal = (domain: string, name?: string | null): LifecycleEmail => ({
- subject: `Need a hand with ${domain}?`,
- text: `${greeting(name)}
+ const listed = sitesIn
+ .slice(0, MAX_LISTED_SITES)
+ .map(s => `${s.domain}\n${s.checkInstallUrl}`)
+ .join("\n\n");
+ return {
+ subject: `Still nothing from ${subjectDomains(domains)}`,
+ text: `${greeting(name)}
+
+Your Rybbit snippets haven't sent any data from ${sitesIn.length} of your sites yet. The three most common causes:
+
+1. The snippet isn't in the <head> of the deployed site (check view-source on the live page)
+2. The site hasn't been redeployed since you added it
+3. An adblocker on your own browser is blocking your test visit - try a private window
+
+Click a link and we'll fetch that site right now and tell you whether the snippet is there:
+
+${listed}${overflowLine(sitesIn.length, "site")}
-${domain} still isn't sending data to Rybbit. I won't keep nudging you - this is the last one.
+Stuck? Reply to this email and I'll take a look personally.${signoff}`,
+ };
+};
+
+export const installFinal = (domains: string[], name?: string | null): LifecycleEmail => {
+ const single = domains.length === 1;
+ const which = single ? domains[0] : `${domains.length} of your sites`;
+ const listed = single ? "" : `\n\n${domains.slice(0, MAX_LISTED_SITES).join("\n")}${overflowLine(domains.length, "site")}`;
+ return {
+ subject: `Need a hand with ${subjectDomains(domains)}?`,
+ text: `${greeting(name)}
+
+${which} still ${single ? "isn't" : "aren't"} sending data to Rybbit.${listed}
+
+I won't keep nudging you - this is the last one.
If you hit a technical wall, reply with your platform (WordPress, Next.js, Shopify...) and I'll send you exact instructions. If you decided Rybbit isn't for you, I'd honestly love to know why.
Either way, thanks for giving us a try.${signoff}`,
-});
+ };
+};
// ---------------------------------------------------------------------------
// Stage 3: data flowing
// ---------------------------------------------------------------------------
-export const siteLive = (domain: string, siteId: number, country: string | null, name?: string | null): LifecycleEmail => ({
- subject: `Rybbit is live on ${domain}`,
- text: `${greeting(name)}
+export interface LiveSite {
+ domain: string;
+ siteId: number;
+}
+
+export const siteLive = (sitesIn: LiveSite[], country: string | null, name?: string | null): LifecycleEmail => {
+ const domains = sitesIn.map(s => s.domain);
+ if (sitesIn.length === 1) {
+ const [{ domain, siteId }] = sitesIn;
+ return {
+ subject: `Rybbit is live on ${domain}`,
+ text: `${greeting(name)}
Rybbit just received its first pageview from ${domain}${country ? ` - a visitor from ${country}` : ""}. Everything is working.
Watch your traffic live: ${appUrl()}/${siteId}
Let it collect data for a couple of days, then I'll send you the first patterns worth looking at.${signoff}`,
-});
+ };
+ }
+
+ const listed = sitesIn
+ .slice(0, MAX_LISTED_SITES)
+ .map(s => `${s.domain}: ${appUrl()}/${s.siteId}`)
+ .join("\n");
+ return {
+ subject: `Rybbit is live on ${subjectDomains(domains)}`,
+ text: `${greeting(name)}
+
+Rybbit has received its first pageviews from ${sitesIn.length} of your sites. Everything is working.
+
+${listed}${overflowLine(sitesIn.length, "site")}
+
+Let them collect data for a couple of days, then I'll send you the first patterns worth looking at.${signoff}`,
+ };
+};
export interface FirstDaysStats {
sessions: number;
@@ -166,13 +274,42 @@ Guide: https://rybbit.com/docs/goals${signoff}`,
// Stage 4: went quiet
// ---------------------------------------------------------------------------
-export const wentQuiet = (domain: string, siteId: number, lastEventAt: string, name?: string | null): LifecycleEmail => ({
- subject: `We stopped hearing from ${domain}`,
- text: `${greeting(name)}
+export interface QuietSite {
+ domain: string;
+ siteId: number;
+ lastEventAt: string;
+}
+
+export const wentQuiet = (sitesIn: QuietSite[], name?: string | null): LifecycleEmail => {
+ const domains = sitesIn.map(s => s.domain);
+ if (sitesIn.length === 1) {
+ const [{ domain, siteId, lastEventAt }] = sitesIn;
+ return {
+ 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.
Check that the snippet is still in your <head>, or see your dashboard: ${appUrl()}/${siteId}
If you removed it on purpose, ignore this - I won't email about it again.${signoff}`,
-});
+ };
+ }
+
+ const listed = sitesIn
+ .slice(0, MAX_LISTED_SITES)
+ .map(s => `${s.domain} - last event ${s.lastEventAt}: ${appUrl()}/${s.siteId}`)
+ .join("\n");
+ return {
+ subject: `We stopped hearing from ${subjectDomains(domains)}`,
+ text: `${greeting(name)}
+
+${sitesIn.length} of your sites were sending data to Rybbit, but we haven't received anything from them for two days or more:
+
+${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>.
+
+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 dd233f81e..2a9313426 100644
--- a/server/src/services/lifecycleEmails/lifecycleEmailService.test.ts
+++ b/server/src/services/lifecycleEmails/lifecycleEmailService.test.ts
@@ -24,7 +24,7 @@ const state = vi.hoisted(() => ({
detectedPlatform: string | null;
}>,
logs: [] as Array<{ userId: string; emailKey: string; sentAt: string }>,
- recentQuietLogs: [] as Array<{ siteId: number; emailKey: 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 }>,
/** site_id -> aggregate stats returned by the ClickHouse batch query */
@@ -54,7 +54,8 @@ const mocks = vi.hoisted(() => ({
detectPlatform: vi.fn(async () => null),
}));
-const insertedStack = vi.hoisted(() => [] as string[]);
+/** one entry per insert call: the keys that call claimed (for LIFO rollback) */
+const insertedStack = vi.hoisted(() => [] as string[][]);
vi.mock("../../db/postgres/postgres.js", () => {
function chain(rows: () => unknown[]) {
@@ -73,8 +74,8 @@ vi.mock("../../db/postgres/postgres.js", () => {
select: (fields: Record<string, unknown>) =>
chain(() => {
if ("scheduledTipEmailIds" in fields) return state.legacyTipUsers;
+ if ("siteId" in fields && "userId" in fields && "sentAt" in fields) return state.recentQuietLogs;
if ("emailKey" in fields && "userId" in fields) return state.logs;
- if ("emailKey" in fields && "siteId" in fields) return state.recentQuietLogs;
if ("role" in fields) return state.memberships;
if ("createdAt" in fields && "email" in fields) return state.users;
if ("detectedPlatform" in fields) return state.sites;
@@ -83,20 +84,22 @@ vi.mock("../../db/postgres/postgres.js", () => {
return state.goals;
}),
insert: () => ({
- values: (row: { userId: string; emailKey: string }) => ({
+ values: (rows: Array<{ userId: string; emailKey: string }>) => ({
onConflictDoNothing: () => ({
returning: async () => {
- const key = `${row.userId}:${row.emailKey}`;
- if (state.sentKeys.has(key)) return [];
- 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(),
- });
- insertedStack.push(key);
- return [{ id: state.sentKeys.size }];
+ const claimed: string[] = [];
+ const returned: Array<{ id: number; emailKey: string }> = [];
+ for (const row of rows) {
+ const key = `${row.userId}:${row.emailKey}`;
+ 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() });
+ claimed.push(key);
+ returned.push({ id: state.sentKeys.size, emailKey: row.emailKey });
+ }
+ if (claimed.length > 0) insertedStack.push(claimed);
+ return returned;
},
}),
}),
@@ -108,17 +111,19 @@ vi.mock("../../db/postgres/postgres.js", () => {
},
}),
}),
- // The service only deletes the row it just inserted (send-failure
- // rollback), so LIFO removal mirrors the real behavior.
+ // The service only deletes the rows it just inserted (send-failure
+ // rollback), so LIFO removal of the last batch mirrors the real behavior.
delete: () => ({
where: async () => {
- const key = insertedStack.pop();
- if (!key) return;
- state.sentKeys.delete(key);
- const [userId, ...rest] = key.split(":");
- const emailKey = rest.join(":");
- const idx = state.logs.findIndex(l => l.userId === userId && l.emailKey === emailKey);
- if (idx >= 0) state.logs.splice(idx, 1);
+ const keys = insertedStack.pop();
+ if (!keys) return;
+ for (const key of keys) {
+ state.sentKeys.delete(key);
+ const [userId, ...rest] = key.split(":");
+ const emailKey = rest.join(":");
+ const idx = state.logs.findIndex(l => l.userId === userId && l.emailKey === emailKey);
+ if (idx >= 0) state.logs.splice(idx, 1);
+ }
},
}),
},
@@ -321,7 +326,9 @@ describe("transition: first data arrives", () => {
addOwnedSite("u1", 42, "acme.com", hoursAgo(20));
state.siteStats.push({ site_id: 42, first_event: hoursAgo(1), last_event: hoursAgo(1), total: 5, pageviews: 5, custom_events: 0 });
await run();
- expect(mocks.sendLifecycleEmail.mock.calls[0][3]).toBe("lifecycle:u1:site_live:42");
+ // Bundled kinds key on the cooldown window, not the member sites, so a
+ // retry after a lost response reuses it even if membership changed.
+ expect(mocks.sendLifecycleEmail.mock.calls[0][3]).toBe("lifecycle:u1:site_live:first");
});
it("does not send it for sites whose first event is old (pre-existing traffic)", async () => {
@@ -432,19 +439,175 @@ describe("state: went quiet", () => {
it("respects the 30-day per-site cooldown for repeat outages", async () => {
quietSite();
- state.recentQuietLogs.push({ siteId: 7, emailKey: "went_quiet:7:2026-08-15" });
+ state.recentQuietLogs.push({ siteId: 7, userId: "owner1", sentAt: daysAgo(20) });
await run();
expect(mocks.sendLifecycleEmail).not.toHaveBeenCalled();
});
- it("sends one owner at most one alert per run even with several quiet sites", async () => {
+ it("rolls an owner's several quiet sites into one email and logs every site", async () => {
quietSite();
state.quietCandidates.push({ site_id: 8, last_event: hoursAgo(52) });
state.establishedSites.push({ site_id: 8, total: 3000 });
state.sites.push({ siteId: 8, domain: "quiet2.com", createdAt: daysAgo(200), organizationId: "org-x", detectedPlatform: null });
await run();
+ expect(sentSubjects()).toEqual(["We stopped hearing from quiet.com and 1 other site"]);
+ const body = mocks.sendLifecycleEmail.mock.calls[0][2];
+ expect(body).toContain("quiet.com");
+ expect(body).toContain("quiet2.com");
+ 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 () => {
+ quietSite();
+ // A different site of the same owner was reported 3 hours ago
+ state.recentQuietLogs.push({ siteId: 99, userId: "owner1", sentAt: hoursAgo(3) });
+ 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;
+ await run();
+ expect(sentSubjects()).toEqual(["We stopped hearing from quiet.com"]);
+ });
+});
+
+describe("multi-site owners", () => {
+ const siteIds = (prefix: string) =>
+ state.logs.filter(l => l.emailKey.startsWith(prefix)).map(l => Number(l.emailKey.split(":")[1])).sort((a, b) => a - b);
+
+ it("bundles every site awaiting a snippet into one email", async () => {
+ addUser("agency", hoursAgo(6));
+ for (let i = 1; i <= 13; i++) addOwnedSite("agency", i, `client${i}.com`, hoursAgo(3));
+ await run();
+ expect(sentSubjects()).toEqual(["One step left for client1.com and 12 other sites"]);
+ const body = mocks.sendLifecycleEmail.mock.calls[0][2];
+ // Ten listed with their own snippet, the rest summarised
+ expect(body).toContain('data-site-id="1"');
+ expect(body).toContain('data-site-id="10"');
+ expect(body).not.toContain('data-site-id="11"');
+ expect(body).toContain("...and 3 more sites.");
+ expect(siteIds("install_snippet:")).toEqual(Array.from({ length: 13 }, (_, i) => i + 1));
+
+ // Nothing further on the next tick: every site is logged
+ await run();
expect(mocks.sendLifecycleEmail).toHaveBeenCalledTimes(1);
});
+
+ it("holds a later site's snippet until 24h after the last install email, then bundles", async () => {
+ addUser("agency", daysAgo(1));
+ addOwnedSite("agency", 1, "first.com", hoursAgo(5));
+ markSent("agency", "install_snippet:1", hoursAgo(4));
+ addOwnedSite("agency", 2, "second.com", hoursAgo(3));
+ addOwnedSite("agency", 3, "third.com", hoursAgo(2));
+ await run();
+ expect(mocks.sendLifecycleEmail).not.toHaveBeenCalled();
+
+ state.logs.length = 0;
+ state.sentKeys.clear();
+ markSent("agency", "install_snippet:1", hoursAgo(25));
+ await run();
+ expect(sentSubjects()).toEqual(["One step left for second.com and 1 other site"]);
+ });
+
+ it("bundles the install check for every site whose snippet went out a day ago", async () => {
+ addUser("agency", daysAgo(3));
+ for (let i = 1; i <= 3; i++) {
+ addOwnedSite("agency", i, `client${i}.com`, daysAgo(2));
+ markSent("agency", `install_snippet:${i}`, hoursAgo(30));
+ }
+ await run();
+ expect(sentSubjects()).toEqual(["Still nothing from client1.com and 2 other sites"]);
+ const body = mocks.sendLifecycleEmail.mock.calls[0][2];
+ expect(body).toContain("/api/site/check-install?siteId=1&");
+ expect(body).toContain("/api/site/check-install?siteId=3&");
+ expect(siteIds("install_check:")).toEqual([1, 2, 3]);
+ });
+
+ it("sends the snippet stage before the check stage when both are due", async () => {
+ addUser("agency", daysAgo(3));
+ addOwnedSite("agency", 1, "old.com", daysAgo(2));
+ markSent("agency", "install_snippet:1", hoursAgo(30));
+ addOwnedSite("agency", 2, "new.com", hoursAgo(2));
+ await run();
+ expect(sentSubjects()).toEqual(["One step left for new.com"]);
+ });
+
+ it("bundles 'you're live' for every site that got data since the last one", async () => {
+ addUser("agency", daysAgo(1));
+ for (let i = 1; i <= 4; i++) {
+ addOwnedSite("agency", i, `client${i}.com`, hoursAgo(20));
+ state.siteStats.push({ site_id: i, first_event: hoursAgo(i), last_event: hoursAgo(0.1), total: 5, pageviews: 5, custom_events: 0 });
+ }
+ await run();
+ expect(sentSubjects()).toEqual(["Rybbit is live on client1.com and 3 other sites"]);
+ const body = mocks.sendLifecycleEmail.mock.calls[0][2];
+ expect(body).toContain("client4.com: https://app.rybbit.io/4");
+ expect(siteIds("site_live:")).toEqual([1, 2, 3, 4]);
+ });
+
+ it("holds a second 'you're live' for 24h but not behind an install email", async () => {
+ addUser("agency", daysAgo(1));
+ addOwnedSite("agency", 1, "first.com", hoursAgo(20));
+ addOwnedSite("agency", 2, "second.com", hoursAgo(20));
+ markSent("agency", "site_live:1", hoursAgo(2));
+ markSent("agency", "install_snippet:2", hoursAgo(1));
+ state.siteStats.push({ site_id: 1, first_event: hoursAgo(3), last_event: hoursAgo(0.1), total: 50, pageviews: 50, custom_events: 0 });
+ state.siteStats.push({ site_id: 2, first_event: hoursAgo(0.5), last_event: hoursAgo(0.1), total: 5, pageviews: 5, custom_events: 0 });
+ await run();
+ expect(mocks.sendLifecycleEmail).not.toHaveBeenCalled();
+
+ // Same state, but the first live email is a day old: only the site_live
+ // cooldown matters, the recent install email doesn't block a confirmation.
+ state.logs.length = 0;
+ state.sentKeys.clear();
+ markSent("agency", "site_live:1", hoursAgo(25));
+ markSent("agency", "install_snippet:2", hoursAgo(1));
+ await run();
+ expect(sentSubjects()).toEqual(["Rybbit is live on second.com"]);
+ });
+
+ it("reuses the idempotency key on retry even when bundle membership changed, and rotates it after success", async () => {
+ addUser("agency", daysAgo(1));
+ for (let i = 1; i <= 2; i++) {
+ addOwnedSite("agency", i, `client${i}.com`, hoursAgo(20));
+ state.siteStats.push({ site_id: i, first_event: hoursAgo(1), last_event: hoursAgo(0.1), total: 5, pageviews: 5, custom_events: 0 });
+ }
+ // Resend may have accepted this bundle even though we saw a failure.
+ mocks.sendLifecycleEmail.mockResolvedValueOnce(false);
+ await run();
+ expect(state.logs.filter(l => l.emailKey.startsWith("site_live:")).length).toBe(0);
+
+ // A third site goes live before the retry, so the bundle now has 3 members.
+ addOwnedSite("agency", 3, "client3.com", hoursAgo(20));
+ state.siteStats.push({ site_id: 3, first_event: hoursAgo(0.5), last_event: hoursAgo(0.1), total: 5, pageviews: 5, custom_events: 0 });
+ await run();
+ expect(mocks.sendLifecycleEmail).toHaveBeenCalledTimes(2);
+ const [failed, retried] = mocks.sendLifecycleEmail.mock.calls;
+ expect(retried[1]).toBe("Rybbit is live on client1.com and 2 other sites");
+ // Same key: Resend dedupes against the possibly-accepted first attempt
+ // instead of delivering a second email.
+ expect(retried[3]).toBe(failed[3]);
+ expect(siteIds("site_live:")).toEqual([1, 2, 3]);
+
+ // After a successful send the next window gets a different key.
+ state.logs.length = 0;
+ state.sentKeys.clear();
+ markSent("agency", "site_live:1", hoursAgo(25));
+ state.siteStats.length = 0;
+ state.siteStats.push({ site_id: 2, first_event: hoursAgo(1), last_event: hoursAgo(0.1), total: 5, pageviews: 5, custom_events: 0 });
+ await run();
+ const next = mocks.sendLifecycleEmail.mock.calls[2][3];
+ expect(next).toMatch(/^lifecycle:agency:site_live:\d+$/);
+ expect(next).not.toBe(failed[3]);
+ });
+
+ it("single-key emails keep the per-key idempotency form", async () => {
+ addUser("u1", hoursAgo(4));
+ await run();
+ expect(mocks.sendLifecycleEmail.mock.calls[0][3]).toBe("lifecycle:u1:no_site_1");
+ });
});
describe("rollout", () => {
diff --git a/server/src/services/lifecycleEmails/lifecycleEmailService.ts b/server/src/services/lifecycleEmails/lifecycleEmailService.ts
index 11f585639..b134cd5c7 100644
--- a/server/src/services/lifecycleEmails/lifecycleEmailService.ts
+++ b/server/src/services/lifecycleEmails/lifecycleEmailService.ts
@@ -19,6 +19,12 @@ import { detectPlatform, platformForKey, type PlatformInfo } from "./platformDet
* fire at most once. At most one email per user per run (enforced across both
* passes via a per-run set), with a minimum gap between educational sends.
*
+ * 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.
+ *
* 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
* moves to multiple replicas, the per-run set must become a distributed
@@ -27,6 +33,7 @@ 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 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
@@ -50,6 +57,21 @@ const parseTs = (value: string): DateTime => {
return sql.isValid ? sql : DateTime.fromISO(value, { zone: "utc" });
};
+/** Latest sentAt among log keys starting with any of the prefixes, or null. */
+const lastSentWithPrefix = (sentLog: Map<string, DateTime>, prefixes: string[]): DateTime | null => {
+ let latest: DateTime | null = null;
+ for (const [key, at] of sentLog) {
+ if (!prefixes.some(p => key.startsWith(p))) continue;
+ if (!latest || at > latest) latest = at;
+ }
+ return latest;
+};
+
+interface BundleEntry {
+ key: string;
+ siteId: number | null;
+}
+
const countryName = (code: string | null): string | null => {
if (!code) return null;
try {
@@ -219,47 +241,81 @@ class LifecycleEmailService {
}
/**
- * Record + send. The insert happens first with the unique index as the guard,
- * so a re-entrant run can never double-send; if the send then fails, the row
- * is removed so the next tick retries. The lifecycle key doubles as the
- * Resend idempotency key so an "accepted but response lost" retry can't
- * deliver twice.
+ * Record + send one email covering one or more per-site keys. The inserts
+ * happen first with the unique index as the guard, so a re-entrant run can
+ * never double-send; if the send then fails, the rows are removed so the next
+ * tick retries. Keys that already exist are dropped from the bundle and the
+ * email is built from the ones actually claimed.
+ *
+ * A send failure can't be told apart from "accepted but response lost", so
+ * the rollback-and-retry is only safe because the Resend idempotency key is
+ * stable across retries: it must not depend on which sites happen to be in
+ * the bundle (membership can change between ticks) - see bundleKey. Resend
+ * then either returns the original response or rejects the mismatched
+ * payload; it never delivers a second email.
*/
- private async sendOnce(
+ private async sendBundle(
userId: string,
email: string,
- emailKey: string,
- siteId: number | null,
- build: () => Promise<content.LifecycleEmail | null> | content.LifecycleEmail | null
+ entries: BundleEntry[],
+ idempotencyKey: string,
+ build: (claimed: BundleEntry[]) => Promise<content.LifecycleEmail | null> | content.LifecycleEmail | null
): Promise<boolean> {
- const [inserted] = await db
+ if (entries.length === 0) return false;
+ const inserted = await db
.insert(lifecycleEmailLog)
- .values({ userId, emailKey, siteId })
+ .values(entries.map(e => ({ userId, emailKey: e.key, siteId: e.siteId })))
.onConflictDoNothing()
- .returning({ id: lifecycleEmailLog.id });
- if (!inserted) return false; // already sent
+ .returning({ id: lifecycleEmailLog.id, emailKey: lifecycleEmailLog.emailKey });
+ if (inserted.length === 0) return false; // all already sent
+
+ const insertedIds = inserted.map(r => r.id);
+ const claimedKeys = new Set(inserted.map(r => r.emailKey));
+ const claimed = entries.filter(e => claimedKeys.has(e.key));
+ const rollback = () => db.delete(lifecycleEmailLog).where(inArray(lifecycleEmailLog.id, insertedIds));
try {
- const message = await build();
+ const message = await build(claimed);
if (!message) {
- await db.delete(lifecycleEmailLog).where(eq(lifecycleEmailLog.id, inserted.id));
+ await rollback();
return false;
}
- const sent = await sendLifecycleEmail(email, message.subject, message.text, `lifecycle:${userId}:${emailKey}`);
+ const sent = await sendLifecycleEmail(email, message.subject, message.text, idempotencyKey);
if (!sent) {
- await db.delete(lifecycleEmailLog).where(eq(lifecycleEmailLog.id, inserted.id));
+ await rollback();
return false;
}
this.emailedThisRun.add(userId);
- this.logger.info({ userId, emailKey, siteId }, "Sent lifecycle email");
+ this.logger.info({ userId, emailKeys: claimed.map(e => e.key) }, "Sent lifecycle email");
return true;
} catch (error) {
- this.logger.error({ err: error, userId, emailKey }, "Error sending lifecycle email");
- await db.delete(lifecycleEmailLog).where(eq(lifecycleEmailLog.id, inserted.id));
+ this.logger.error({ err: error, userId, emailKeys: claimed.map(e => e.key) }, "Error sending lifecycle email");
+ await rollback();
return false;
}
}
+ /**
+ * Idempotency key for a bundled kind. Each kind reaches a user at most once
+ * per cooldown window, so "the window since this kind's last successful
+ * send" identifies the email: a rolled-back send leaves lastSent unchanged
+ * and the retry reuses the key whatever sites are eligible by then, while a
+ * successful send advances lastSent and the next bundle gets a fresh key.
+ */
+ private bundleKey(userId: string, kind: string, lastSent: DateTime | null): string {
+ return `lifecycle:${userId}:${kind}:${lastSent ? lastSent.toMillis() : "first"}`;
+ }
+
+ private sendOnce(
+ userId: string,
+ email: string,
+ emailKey: string,
+ siteId: number | null,
+ build: () => Promise<content.LifecycleEmail | null> | content.LifecycleEmail | null
+ ): Promise<boolean> {
+ return this.sendBundle(userId, email, [{ key: emailKey, siteId }], `lifecycle:${userId}:${emailKey}`, build);
+ }
+
// -------------------------------------------------------------------------
// Rollout: cancel tips the retired drip already scheduled in Resend
// -------------------------------------------------------------------------
@@ -400,21 +456,33 @@ class LifecycleEmailService {
const unsubscribed = () => isContactUnsubscribed(u.email);
+ const lastLiveSent = lastSentWithPrefix(sentLog, ["site_live:"]);
+ const lastInstallSent = lastSentWithPrefix(sentLog, ["install_"]);
+ const cooldownElapsed = (last: DateTime | null) => !last || now.diff(last, "hours").hours >= KIND_COOLDOWN_HOURS;
+
// --- Transition: a site just received its first data -> "you're live" ---
// Exempt from the gap; it's a confirmation, not education. Only fires while
- // the first event is fresh so pre-existing sites don't get it late.
- for (const site of userSites) {
+ // the first event is fresh so pre-existing sites don't get it late. All
+ // sites that went live since the last such email share one message.
+ const liveSites = userSites.filter(site => {
const s = stats.get(site.siteId);
- if (!s || s.total === 0) continue;
- const firstEventAge = now.diff(s.firstEvent, "hours").hours;
- if (firstEventAge > 72) continue;
- if (sentLog.has(`site_live:${site.siteId}`)) continue;
+ if (!s || s.total === 0) return false;
+ if (now.diff(s.firstEvent, "hours").hours > 72) return false;
+ return !sentLog.has(`site_live:${site.siteId}`);
+ });
+ if (liveSites.length > 0 && cooldownElapsed(lastLiveSent)) {
if (await unsubscribed()) return;
-
- const sent = await this.sendOnce(u.id, u.email, `site_live:${site.siteId}`, site.siteId, async () => {
- const first = await this.fetchFirstPageview(site.siteId);
- return content.siteLive(site.domain, site.siteId, countryName(first?.country ?? null), u.name);
- });
+ const sent = await this.sendBundle(
+ u.id,
+ u.email,
+ liveSites.map(site => ({ key: `site_live:${site.siteId}`, siteId: site.siteId })),
+ this.bundleKey(u.id, "site_live", lastLiveSent),
+ async claimed => {
+ const chosen = liveSites.filter(site => claimed.some(e => e.siteId === site.siteId));
+ const first = chosen.length === 1 ? await this.fetchFirstPageview(chosen[0].siteId) : null;
+ return content.siteLive(chosen, countryName(first?.country ?? null), u.name);
+ }
+ );
if (sent) return;
}
@@ -432,41 +500,92 @@ class LifecycleEmailService {
}
// --- Install track: evaluated per site, so a working site doesn't
- // suppress install help for the owner's other new sites ---
+ // suppress install help for the owner's other new sites. Sent per user:
+ // every site at the same stage goes into one email, and the track sends
+ // at most one email per KIND_COOLDOWN_HOURS, snippet stage first ---
const noDataSites = userSites
.filter(site => !stats.get(site.siteId) && now.diff(site.createdAt, "days").days < COHORT_DAYS)
.sort((a, b) => a.createdAt.toMillis() - b.createdAt.toMillis());
- for (const site of noDataSites) {
- const siteAge = now.diff(site.createdAt, "hours").hours;
- const snippetKey = `install_snippet:${site.siteId}`;
- const checkKey = `install_check:${site.siteId}`;
- const finalKey = `install_final:${site.siteId}`;
- const snippetSentAt = sentLog.get(snippetKey);
- const checkSentAt = sentLog.get(checkKey);
-
- if (!sentLog.has(snippetKey)) {
- // The snippet email is the user's next step right after creating a
- // site; it is exempt from the educational gap.
- if (siteAge < 1) continue;
+ if (noDataSites.length > 0 && cooldownElapsed(lastInstallSent)) {
+ // One install email per window, so the three stages share the key.
+ const installKey = this.bundleKey(u.id, "install", lastInstallSent);
+ const hoursSince = (key: string) => {
+ const at = sentLog.get(key);
+ return at ? now.diff(at, "hours").hours : null;
+ };
+ const snippetKey = (id: number) => `install_snippet:${id}`;
+ const checkKey = (id: number) => `install_check:${id}`;
+ const finalKey = (id: number) => `install_final:${id}`;
+
+ // The snippet email is the user's next step right after creating a
+ // site; it is exempt from the educational gap.
+ const snippetDue = noDataSites.filter(
+ site => !sentLog.has(snippetKey(site.siteId)) && now.diff(site.createdAt, "hours").hours >= 1
+ );
+ if (snippetDue.length > 0) {
if (await unsubscribed()) return;
- const sent = await this.sendOnce(u.id, u.email, snippetKey, site.siteId, async () => {
- const platform = await this.resolvePlatform(site);
- return content.installSnippet(site.domain, site.siteId, platform, u.name);
- });
+ const sent = await this.sendBundle(
+ u.id,
+ u.email,
+ snippetDue.map(site => ({ key: snippetKey(site.siteId), siteId: site.siteId })),
+ installKey,
+ async claimed => {
+ const chosen = snippetDue.filter(site => claimed.some(e => e.siteId === site.siteId));
+ const withPlatform: content.SnippetSite[] = [];
+ for (const site of chosen) {
+ withPlatform.push({ domain: site.domain, siteId: site.siteId, platform: await this.resolvePlatform(site) });
+ }
+ return content.installSnippet(withPlatform, u.name);
+ }
+ );
if (sent) return;
- } else if (!sentLog.has(checkKey) && snippetSentAt && now.diff(snippetSentAt, "hours").hours >= 24) {
- // Timed from the snippet email, not site age, so a pre-existing site
- // picked up at rollout doesn't get two install emails in one hour.
+ }
+
+ // Timed from the snippet email, not site age, so a pre-existing site
+ // picked up at rollout doesn't get two install emails in one hour.
+ const checkDue = noDataSites.filter(site => {
+ if (sentLog.has(checkKey(site.siteId))) return false;
+ const since = hoursSince(snippetKey(site.siteId));
+ return since !== null && since >= 24;
+ });
+ if (checkDue.length > 0) {
if (await unsubscribed()) return;
- const sent = await this.sendOnce(u.id, u.email, checkKey, site.siteId, () =>
- content.installCheck(site.domain, this.checkInstallUrl(site.siteId, site.domain), u.name)
+ const sent = await this.sendBundle(
+ u.id,
+ u.email,
+ checkDue.map(site => ({ key: checkKey(site.siteId), siteId: site.siteId })),
+ installKey,
+ claimed =>
+ content.installCheck(
+ checkDue
+ .filter(site => claimed.some(e => e.siteId === site.siteId))
+ .map(site => ({ domain: site.domain, checkInstallUrl: this.checkInstallUrl(site.siteId, site.domain) })),
+ u.name
+ )
);
if (sent) return;
- } else if (!sentLog.has(finalKey) && checkSentAt && now.diff(checkSentAt, "hours").hours >= 96 && gapElapsed) {
+ }
+
+ const finalDue = gapElapsed
+ ? noDataSites.filter(site => {
+ if (sentLog.has(finalKey(site.siteId))) return false;
+ const since = hoursSince(checkKey(site.siteId));
+ return since !== null && since >= 96;
+ })
+ : [];
+ if (finalDue.length > 0) {
if (await unsubscribed()) return;
- const sent = await this.sendOnce(u.id, u.email, finalKey, site.siteId, () =>
- content.installFinal(site.domain, u.name)
+ const sent = await this.sendBundle(
+ u.id,
+ u.email,
+ finalDue.map(site => ({ key: finalKey(site.siteId), siteId: site.siteId })),
+ installKey,
+ claimed =>
+ content.installFinal(
+ finalDue.filter(site => claimed.some(e => e.siteId === site.siteId)).map(site => site.domain),
+ u.name
+ )
);
if (sent) return;
}
@@ -563,9 +682,10 @@ class LifecycleEmailService {
if (quietSites.length === 0) return;
// 30-day per-site cooldown: a recovered-then-quiet-again site alerts at
- // most monthly even though each outage gets its own email key.
+ // most monthly even though each outage gets its own email key. The same
+ // rows give each owner's last went-quiet email for the per-user cooldown.
const recentQuietLogs = await db
- .select({ siteId: lifecycleEmailLog.siteId, emailKey: lifecycleEmailLog.emailKey })
+ .select({ siteId: lifecycleEmailLog.siteId, userId: lifecycleEmailLog.userId, sentAt: lifecycleEmailLog.sentAt })
.from(lifecycleEmailLog)
.where(
and(
@@ -574,6 +694,12 @@ class LifecycleEmailService {
)
);
const recentlyAlerted = new Set(recentQuietLogs.map(r => r.siteId));
+ const lastQuietEmailByUser = new Map<string, DateTime>();
+ for (const r of recentQuietLogs) {
+ const at = parseTs(r.sentAt);
+ const prev = lastQuietEmailByUser.get(r.userId);
+ if (!prev || at > prev) lastQuietEmailByUser.set(r.userId, at);
+ }
const orgIds = [...new Set(quietSites.map(s => s.organizationId).filter((id): id is string => !!id))];
const owners =
@@ -588,24 +714,46 @@ 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.
+ const quietByOwner = new Map<string, { owner: (typeof owners)[number]; sites: typeof quietSites }>();
for (const site of quietSites) {
if (recentlyAlerted.has(site.siteId)) continue;
const owner = site.organizationId ? ownerByOrg.get(site.organizationId) : null;
if (!owner) continue;
- // One email per user per run, across both passes: an owner with five
- // quiet sites (or one who just got an onboarding email) gets one message.
+ const entry = quietByOwner.get(owner.userId) ?? { owner, sites: [] };
+ entry.sites.push(site);
+ quietByOwner.set(owner.userId, entry);
+ }
+
+ for (const { owner, sites: ownerSites } of quietByOwner.values()) {
+ // One email per user per run, across both passes: an owner who just got
+ // 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;
try {
if (await isContactUnsubscribed(owner.email)) continue;
- const lastEvent = lastEventBySite.get(site.siteId);
// Per-outage key: the date of the last event identifies the outage, so
// a site that recovers and goes quiet again next month can alert again.
- const outageKey = `went_quiet:${site.siteId}:${lastEvent?.toFormat("yyyy-MM-dd") ?? "unknown"}`;
- await this.sendOnce(owner.userId, owner.email, outageKey, site.siteId, () =>
- content.wentQuiet(site.domain, site.siteId, lastEvent?.toFormat("MMMM d 'at' HH:mm 'UTC'") ?? "two days ago", owner.name)
+ const entries = ownerSites.map(site => ({
+ key: `went_quiet:${site.siteId}:${lastEventBySite.get(site.siteId)?.toFormat("yyyy-MM-dd") ?? "unknown"}`,
+ siteId: site.siteId,
+ }));
+ await this.sendBundle(owner.userId, owner.email, entries, this.bundleKey(owner.userId, "went_quiet", lastQuiet), claimed =>
+ content.wentQuiet(
+ ownerSites
+ .filter(site => claimed.some(e => e.siteId === site.siteId))
+ .map(site => ({
+ domain: site.domain,
+ siteId: site.siteId,
+ lastEventAt: lastEventBySite.get(site.siteId)?.toFormat("MMMM d 'at' HH:mm 'UTC'") ?? "two days ago",
+ })),
+ owner.name
+ )
);
} catch (error) {
- this.logger.error({ err: error, siteId: site.siteId }, "Error processing went-quiet email");
+ this.logger.error({ err: error, userId: owner.userId }, "Error processing went-quiet email");
}
}
}