Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. πŸ”₯

(fix/monitoring) Email Confirmation (#3645)

Nicolas84338cb51ca3
diff --git a/apps/api/src/__tests__/snips/v2/lib.ts b/apps/api/src/__tests__/snips/v2/lib.ts
index 581bde158..14f392082 100644
--- a/apps/api/src/__tests__/snips/v2/lib.ts
+++ b/apps/api/src/__tests__/snips/v2/lib.ts
@@ -179,6 +179,26 @@ export async function monitorCheckRaw(
return query ? req.query(query) : req;
}
+export async function monitorEmailConfirmRaw(token: string) {
+ return await request(TEST_API_URL)
+ .post(`/v2/monitor/email/confirm`)
+ .set("Content-Type", "application/json")
+ .send({ token });
+}
+
+export async function monitorEmailUnsubscribeRaw(token: string) {
+ return await request(TEST_API_URL)
+ .post(`/v2/monitor/email/unsubscribe`)
+ .set("Content-Type", "application/json")
+ .send({ token });
+}
+
+export async function monitorEmailConfirmRawViaQuery(token: string) {
+ return await request(TEST_API_URL)
+ .post(`/v2/monitor/email/confirm`)
+ .query({ token });
+}
+
export async function parseRaw(
body: {
options?: Omit<ParseRequestInput, "file">;
diff --git a/apps/api/src/__tests__/snips/v2/monitor.test.ts b/apps/api/src/__tests__/snips/v2/monitor.test.ts
index 12f82c1cd..55d99a81c 100644
--- a/apps/api/src/__tests__/snips/v2/monitor.test.ts
+++ b/apps/api/src/__tests__/snips/v2/monitor.test.ts
@@ -10,6 +10,9 @@ import {
monitorCheckRaw,
monitorCreateRaw,
monitorDeleteRaw,
+ monitorEmailConfirmRaw,
+ monitorEmailConfirmRawViaQuery,
+ monitorEmailUnsubscribeRaw,
monitorGetRaw,
monitorListRaw,
monitorPatchRaw,
@@ -308,6 +311,124 @@ describeIf(ALLOW_TEST_SUITE_WEBSITE && !TEST_SELF_HOST)("/v2/monitor", () => {
2 * scrapeTimeout,
);
+ describe("email recipient opt-in", () => {
+ function externalRecipient(): string {
+ const id = Math.random().toString(36).slice(2, 10);
+ return `optin-${id}@external-test.example`;
+ }
+
+ it("starts external recipients as pending without sending notifications", async () => {
+ const recipient = externalRecipient();
+ const create = await monitorCreateRaw(
+ {
+ name: "opt-in monitor",
+ schedule: { cron: "*/30 * * * *", timezone: "UTC" },
+ targets: [
+ {
+ type: "scrape",
+ urls: [createTestIdUrl()],
+ scrapeOptions: { formats: ["markdown"] },
+ },
+ ],
+ notification: {
+ email: { enabled: true, recipients: [recipient] },
+ },
+ },
+ identity,
+ );
+ expect(create.statusCode).toBe(200);
+ expect(create.body.data.emailRecipientSubscriptions).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ email: recipient.toLowerCase(),
+ status: "pending",
+ source: "opt_in",
+ }),
+ ]),
+ );
+
+ const get = await monitorGetRaw(create.body.data.id, identity);
+ expect(get.body.data.emailRecipientSubscriptions).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ email: recipient.toLowerCase(),
+ status: "pending",
+ }),
+ ]),
+ );
+
+ await monitorDeleteRaw(create.body.data.id, identity);
+ });
+
+ it("rejects malformed confirm/unsubscribe tokens with a 400 JSON error", async () => {
+ const badConfirm = await monitorEmailConfirmRaw("x");
+ expect(badConfirm.statusCode).toBe(400);
+ expect(badConfirm.body).toEqual({
+ success: false,
+ error: "invalid_token",
+ });
+
+ const badUnsub = await monitorEmailUnsubscribeRaw("x");
+ expect(badUnsub.statusCode).toBe(400);
+ expect(badUnsub.body).toEqual({
+ success: false,
+ error: "invalid_token",
+ });
+ });
+
+ it("rejects tokens sent in the query string (body-only)", async () => {
+ // Tokens in URLs leak into access/proxy logs and APM URL tags, so
+ // the controller deliberately ignores query params.
+ const unknownToken = "a".repeat(43);
+ const response = await monitorEmailConfirmRawViaQuery(unknownToken);
+ expect(response.statusCode).toBe(400);
+ expect(response.body).toEqual({
+ success: false,
+ error: "invalid_token",
+ });
+ });
+
+ it("returns 404 JSON for unknown but well-formed tokens", async () => {
+ const unknownToken = "a".repeat(43);
+
+ const confirm = await monitorEmailConfirmRaw(unknownToken);
+ expect(confirm.statusCode).toBe(404);
+ expect(confirm.body).toEqual({
+ success: false,
+ error: "not_found",
+ });
+
+ const unsub = await monitorEmailUnsubscribeRaw(unknownToken);
+ expect(unsub.statusCode).toBe(404);
+ expect(unsub.body).toEqual({
+ success: false,
+ error: "not_found",
+ });
+ });
+
+ it("does not require opt-in when recipients are unset (team-default path)", async () => {
+ const create = await monitorCreateRaw(
+ {
+ name: "team default monitor",
+ schedule: { cron: "*/30 * * * *", timezone: "UTC" },
+ targets: [
+ {
+ type: "scrape",
+ urls: [createTestIdUrl()],
+ scrapeOptions: { formats: ["markdown"] },
+ },
+ ],
+ notification: { email: { enabled: true } },
+ },
+ identity,
+ );
+ expect(create.statusCode).toBe(200);
+ expect(create.body.data.emailRecipientSubscriptions).toEqual([]);
+
+ await monitorDeleteRaw(create.body.data.id, identity);
+ });
+ });
+
it(
"accepts mixed json + git-diff changeTracking modes",
async () => {
diff --git a/apps/api/src/controllers/v2/monitor.ts b/apps/api/src/controllers/v2/monitor.ts
index dae0eea83..71d51647c 100644
--- a/apps/api/src/controllers/v2/monitor.ts
+++ b/apps/api/src/controllers/v2/monitor.ts
@@ -41,6 +41,13 @@ import {
type WebhookLogRow,
} from "../../services/webhook/logs";
import { WebhookEvent } from "../../services/webhook";
+import {
+ confirmRecipientByToken,
+ getMonitorNameById,
+ listMonitorEmailRecipients,
+ unsubscribeRecipientByToken,
+} from "../../services/monitoring/email_recipients";
+import { syncMonitorEmailRecipients } from "../../services/monitoring/email_recipients_sync";
const logger = _logger.child({ module: "monitor-controller" });
@@ -67,7 +74,17 @@ function rejectZdr(
return false;
}
-function serializeMonitor(monitor: any) {
+function serializeMonitor(
+ monitor: any,
+ options?: {
+ emailRecipientSubscriptions?: Array<{
+ email: string;
+ status: "pending" | "confirmed" | "unsubscribed";
+ source: "team" | "opt_in" | "legacy";
+ confirmationEmailSent?: boolean;
+ }>;
+ },
+) {
return {
id: monitor.id,
name: monitor.name,
@@ -82,6 +99,9 @@ function serializeMonitor(monitor: any) {
targets: monitor.targets,
webhook: monitor.webhook,
notification: monitor.notification,
+ ...(options?.emailRecipientSubscriptions !== undefined
+ ? { emailRecipientSubscriptions: options.emailRecipientSubscriptions }
+ : {}),
retentionDays: monitor.retention_days,
estimatedCreditsPerMonth: monitor.estimated_credits_per_month,
lastCheckSummary: monitor.last_check_summary,
@@ -92,6 +112,16 @@ function serializeMonitor(monitor: any) {
};
}
+async function loadEmailRecipientSubscriptions(monitorId: string) {
+ const rows = await listMonitorEmailRecipients(monitorId);
+ return rows.map(r => ({
+ email: r.email,
+ status: r.status,
+ source: r.source,
+ confirmationEmailSent: r.confirmation_sent_at !== null,
+ }));
+}
+
function overlayWebhookLog<T extends { notificationStatus: any }>(
serialized: T,
log: WebhookLogRow | null,
@@ -190,9 +220,19 @@ export async function createMonitorController(
}),
);
+ const sync = await syncMonitorEmailRecipients({ monitor }).catch(error => {
+ logger.warn("Failed to sync monitor email recipients on create", {
+ error,
+ monitorId: monitor.id,
+ });
+ return { recipients: [] };
+ });
+
res.status(200).json({
success: true,
- data: serializeMonitor(monitor),
+ data: serializeMonitor(monitor, {
+ emailRecipientSubscriptions: sync.recipients,
+ }),
});
}
@@ -209,7 +249,7 @@ export async function listMonitorsController(
res.status(200).json({
success: true,
- data: monitors.map(serializeMonitor),
+ data: monitors.map(monitor => serializeMonitor(monitor)),
});
}
@@ -223,9 +263,21 @@ export async function getMonitorController(
return res.status(404).json({ success: false, error: "Monitor not found" });
}
+ const subscriptions = await loadEmailRecipientSubscriptions(monitorId).catch(
+ error => {
+ logger.warn("Failed to load email recipient subscriptions", {
+ error,
+ monitorId,
+ });
+ return [];
+ },
+ );
+
res.status(200).json({
success: true,
- data: serializeMonitor(monitor),
+ data: serializeMonitor(monitor, {
+ emailRecipientSubscriptions: subscriptions,
+ }),
});
}
@@ -303,9 +355,28 @@ export async function updateMonitorController(
}),
);
+ // Only re-sync when notification config actually changed.
+ let subscriptions: Awaited<
+ ReturnType<typeof loadEmailRecipientSubscriptions>
+ > = [];
+ if (input.notification !== undefined) {
+ const sync = await syncMonitorEmailRecipients({ monitor }).catch(error => {
+ logger.warn("Failed to sync monitor email recipients on update", {
+ error,
+ monitorId: monitor.id,
+ });
+ return { recipients: [] };
+ });
+ subscriptions = sync.recipients;
+ } else {
+ subscriptions = await loadEmailRecipientSubscriptions(monitor.id);
+ }
+
res.status(200).json({
success: true,
- data: serializeMonitor(monitor),
+ data: serializeMonitor(monitor, {
+ emailRecipientSubscriptions: subscriptions,
+ }),
});
}
@@ -500,3 +571,138 @@ export async function getMonitorCheckController(
},
});
}
+
+// Unauthenticated POST endpoints β€” the token is the credential. Backs the
+// firecrawl-web confirm/unsubscribe pages; POST-only so passive GET scanners
+// can't consume tokens against the dashboard URL.
+
+const emailActionBodySchema = z.object({
+ // 32-byte base64url is 43 chars; range leaves room for future formats.
+ token: z.string().min(16).max(64),
+});
+
+type EmailActionResponse =
+ | {
+ success: true;
+ result: "confirmed" | "already_confirmed" | "unsubscribed" | "already_unsubscribed";
+ email: string;
+ monitorName: string | null;
+ }
+ | {
+ success: false;
+ error: "invalid_token" | "not_found" | "internal_error";
+ };
+
+
+function parseTokenFromRequest(req: { body?: unknown }): string | null {
+ const candidate =
+ req.body && typeof req.body === "object"
+ ? (req.body as { token?: unknown }).token
+ : null;
+ const parsed = emailActionBodySchema.safeParse({ token: candidate });
+ return parsed.success ? parsed.data.token : null;
+}
+
+export async function confirmMonitorEmailController(
+ req: { body?: unknown },
+ res: Response,
+) {
+ const token = parseTokenFromRequest(req);
+ if (!token) {
+ const body: EmailActionResponse = {
+ success: false,
+ error: "invalid_token",
+ };
+ return res.status(400).json(body);
+ }
+
+ try {
+ const row = await confirmRecipientByToken(token);
+ if (!row) {
+ const body: EmailActionResponse = {
+ success: false,
+ error: "not_found",
+ };
+ return res.status(404).json(body);
+ }
+
+ const monitorName = await getMonitorNameById(row.monitor_id);
+
+ // Heuristic: if confirmed_at is older than 5s, this call was a no-op
+ // (already confirmed). Used only to flavor the rendered page.
+ let result: "confirmed" | "already_confirmed" | "already_unsubscribed";
+ if (row.status === "unsubscribed") {
+ result = "already_unsubscribed";
+ } else if (
+ row.confirmed_at !== null &&
+ new Date().getTime() - new Date(row.confirmed_at).getTime() > 5_000
+ ) {
+ result = "already_confirmed";
+ } else {
+ result = "confirmed";
+ }
+
+ const body: EmailActionResponse = {
+ success: true,
+ result,
+ email: row.email,
+ monitorName,
+ };
+ return res.status(200).json(body);
+ } catch (error) {
+ logger.error("Failed to confirm monitor email recipient", { error });
+ const body: EmailActionResponse = {
+ success: false,
+ error: "internal_error",
+ };
+ return res.status(500).json(body);
+ }
+}
+
+export async function unsubscribeMonitorEmailController(
+ req: { body?: unknown },
+ res: Response,
+) {
+ const token = parseTokenFromRequest(req);
+ if (!token) {
+ const body: EmailActionResponse = {
+ success: false,
+ error: "invalid_token",
+ };
+ return res.status(400).json(body);
+ }
+
+ try {
+ const row = await unsubscribeRecipientByToken(token);
+ if (!row) {
+ const body: EmailActionResponse = {
+ success: false,
+ error: "not_found",
+ };
+ return res.status(404).json(body);
+ }
+
+ const monitorName = await getMonitorNameById(row.monitor_id);
+
+ const result: "unsubscribed" | "already_unsubscribed" =
+ row.unsubscribed_at !== null &&
+ new Date().getTime() - new Date(row.unsubscribed_at).getTime() > 5_000
+ ? "already_unsubscribed"
+ : "unsubscribed";
+
+ const body: EmailActionResponse = {
+ success: true,
+ result,
+ email: row.email,
+ monitorName,
+ };
+ return res.status(200).json(body);
+ } catch (error) {
+ logger.error("Failed to unsubscribe monitor email recipient", { error });
+ const body: EmailActionResponse = {
+ success: false,
+ error: "internal_error",
+ };
+ return res.status(500).json(body);
+ }
+}
diff --git a/apps/api/src/routes/v2.ts b/apps/api/src/routes/v2.ts
index e7b6e9e35..77e8f57e3 100644
--- a/apps/api/src/routes/v2.ts
+++ b/apps/api/src/routes/v2.ts
@@ -68,6 +68,7 @@ import {
scrapeStopInteractiveBrowserController,
} from "../controllers/v2/scrape-browser";
import {
+ confirmMonitorEmailController,
createMonitorController,
deleteMonitorController,
getMonitorCheckController,
@@ -75,6 +76,7 @@ import {
listMonitorChecksController,
listMonitorsController,
runMonitorController,
+ unsubscribeMonitorEmailController,
updateMonitorController,
} from "../controllers/v2/monitor";
@@ -484,6 +486,14 @@ v2Router.get(
wrap(listMonitorsController),
);
+// Public, unauthenticated β€” token in body is the credential. Registered
+// before /monitor/:monitorId so "email" isn't parsed as a monitor UUID.
+v2Router.post("/monitor/email/confirm", wrap(confirmMonitorEmailController));
+v2Router.post(
+ "/monitor/email/unsubscribe",
+ wrap(unsubscribeMonitorEmailController),
+);
+
v2Router.get(
"/monitor/:monitorId",
authMiddleware(RateLimiterMode.CrawlStatus),
diff --git a/apps/api/src/services/monitoring/email_recipients.test.ts b/apps/api/src/services/monitoring/email_recipients.test.ts
new file mode 100644
index 000000000..8e7b60e2d
--- /dev/null
+++ b/apps/api/src/services/monitoring/email_recipients.test.ts
@@ -0,0 +1,313 @@
+type QueryResult = { data: unknown; error: unknown };
+type ChainOp = "select" | "insert" | "update" | "delete" | "unknown";
+type ClientKind = "primary" | "rr";
+
+type CallRecord = { client: ClientKind; op: ChainOp };
+
+const fromPrimary = jest.fn();
+const fromRR = jest.fn();
+const calls: CallRecord[] = [];
+
+// Each test queues responses in the order the code under test will execute
+// queries. The fluent chain swallows any sequence of select/insert/update/
+// eq/neq calls and resolves at .maybeSingle() / .single() with the next
+// queued result. Tests stay explicit about query order without coupling to
+// the precise method chain shape.
+type QueuedResponse = (
+ client: ClientKind,
+ op: ChainOp,
+) => Promise<QueryResult>;
+let queue: QueuedResponse[] = [];
+
+function queueResponses(responses: QueuedResponse[]): void {
+ queue = [...responses];
+}
+
+function makeChain(client: ClientKind): any {
+ let op: ChainOp | null = null;
+ const setOp = (next: ChainOp) => {
+ if (op === null) op = next;
+ };
+ const resolve = (): Promise<QueryResult> => {
+ const finalOp = op ?? "unknown";
+ calls.push({ client, op: finalOp });
+ const next = queue.shift();
+ if (!next) {
+ throw new Error(
+ `No queued Supabase response for client=${client} op=${finalOp} (queue exhausted)`,
+ );
+ }
+ return next(client, finalOp);
+ };
+ const builder: any = {
+ select: () => {
+ setOp("select");
+ return builder;
+ },
+ insert: () => {
+ setOp("insert");
+ return builder;
+ },
+ update: () => {
+ setOp("update");
+ return builder;
+ },
+ delete: () => {
+ setOp("delete");
+ return builder;
+ },
+ eq: () => builder,
+ neq: () => builder,
+ in: () => builder,
+ maybeSingle: resolve,
+ single: resolve,
+ };
+ return builder;
+}
+
+jest.mock("../supabase", () => ({
+ supabase_service: {
+ from: (...args: unknown[]) => fromPrimary(...args),
+ },
+ supabase_rr_service: {
+ from: (...args: unknown[]) => fromRR(...args),
+ },
+}));
+
+import {
+ confirmRecipientByToken,
+ ensureMonitorEmailRecipient,
+ unsubscribeRecipientByToken,
+} from "./email_recipients";
+
+beforeEach(() => {
+ queue = [];
+ calls.length = 0;
+ fromPrimary.mockReset();
+ fromRR.mockReset();
+ fromPrimary.mockImplementation(() => makeChain("primary"));
+ fromRR.mockImplementation(() => makeChain("rr"));
+});
+
+function recipientRow(overrides: Record<string, unknown> = {}) {
+ return {
+ id: "rec-1",
+ monitor_id: "monitor-1",
+ team_id: "team-1",
+ email: "[email protected]",
+ status: "pending",
+ token: "tok-1",
+ source: "opt_in",
+ confirmation_sent_at: null,
+ confirmed_at: null,
+ unsubscribed_at: null,
+ last_notified_at: null,
+ created_at: "now",
+ updated_at: "now",
+ ...overrides,
+ };
+}
+
+const baseEnsureInput = {
+ monitorId: "monitor-1",
+ teamId: "team-1",
+ input: {
+ email: "[email protected]",
+ source: "opt_in" as const,
+ status: "pending" as const,
+ },
+};
+
+const ok = (data: unknown): QueuedResponse => () =>
+ Promise.resolve({ data, error: null });
+const fail = (error: unknown): QueuedResponse => () =>
+ Promise.resolve({ data: null, error });
+
+describe("ensureMonitorEmailRecipient", () => {
+ it("returns existing row when the recipient already exists (no insert)", async () => {
+ const existing = recipientRow({ status: "confirmed", source: "team" });
+ queueResponses([ok(existing)]);
+
+ const result = await ensureMonitorEmailRecipient(baseEnsureInput);
+
+ expect(result).toEqual({ row: existing, created: false });
+ expect(queue.length).toBe(0);
+ });
+
+ it("inserts and returns created=true when no row exists", async () => {
+ const inserted = recipientRow();
+ queueResponses([ok(null), ok(inserted)]);
+
+ const result = await ensureMonitorEmailRecipient(baseEnsureInput);
+
+ expect(result).toEqual({ row: inserted, created: true });
+ });
+
+ it("treats a concurrent-insert unique violation as not-created (no throw)", async () => {
+ const winnerRow = recipientRow({ id: "rec-winner" });
+ queueResponses([
+ ok(null),
+ fail({ code: "23505", message: "duplicate key" }),
+ ok(winnerRow),
+ ]);
+
+ const result = await ensureMonitorEmailRecipient(baseEnsureInput);
+
+ expect(result).toEqual({ row: winnerRow, created: false });
+ // The race-recovery re-fetch MUST hit the primary; the read replica may
+ // not yet have the row the concurrent writer just committed.
+ expect(calls.map(c => ({ client: c.client, op: c.op }))).toEqual([
+ { client: "rr", op: "select" },
+ { client: "primary", op: "insert" },
+ { client: "primary", op: "select" },
+ ]);
+ });
+
+ it("rethrows non-unique insert errors", async () => {
+ queueResponses([
+ ok(null),
+ fail({ code: "42501", message: "permission denied" }),
+ ]);
+
+ await expect(ensureMonitorEmailRecipient(baseEnsureInput)).rejects.toThrow(
+ /permission denied/,
+ );
+ });
+
+ it("rethrows unique violations when no winning row can be re-fetched", async () => {
+ queueResponses([
+ ok(null),
+ fail({ code: "23505", message: "duplicate key" }),
+ ok(null),
+ ]);
+
+ await expect(ensureMonitorEmailRecipient(baseEnsureInput)).rejects.toThrow(
+ /duplicate key/,
+ );
+ });
+});
+
+describe("confirmRecipientByToken", () => {
+ it("transitions pending β†’ confirmed when no race", async () => {
+ const pending = recipientRow({ status: "pending" });
+ const confirmed = recipientRow({
+ status: "confirmed",
+ confirmed_at: "now",
+ });
+ queueResponses([ok(pending), ok(confirmed)]);
+
+ const result = await confirmRecipientByToken("tok-1");
+
+ expect(result).toEqual(confirmed);
+ });
+
+ it("returns the row unchanged when status is already confirmed (no UPDATE)", async () => {
+ const confirmed = recipientRow({
+ status: "confirmed",
+ confirmed_at: "now",
+ });
+ queueResponses([ok(confirmed)]);
+
+ const result = await confirmRecipientByToken("tok-1");
+
+ expect(result).toEqual(confirmed);
+ });
+
+ it("returns the row unchanged when status is unsubscribed (no UPDATE)", async () => {
+ const unsubscribed = recipientRow({
+ status: "unsubscribed",
+ unsubscribed_at: "now",
+ });
+ queueResponses([ok(unsubscribed)]);
+
+ const result = await confirmRecipientByToken("tok-1");
+
+ expect(result).toEqual(unsubscribed);
+ });
+
+ it("does NOT overwrite a racing unsubscribe β€” refetches and returns it", async () => {
+ // SELECT sees pending, but between SELECT and our conditional UPDATE
+ // another caller unsubscribed the row. The UPDATE WHERE status='pending'
+ // affects 0 rows, and we re-fetch to discover the unsubscribed state.
+ const pending = recipientRow({ status: "pending" });
+ const unsubscribed = recipientRow({
+ status: "unsubscribed",
+ unsubscribed_at: "now",
+ });
+ queueResponses([ok(pending), ok(null), ok(unsubscribed)]);
+
+ const result = await confirmRecipientByToken("tok-1");
+
+ expect(result).toEqual(unsubscribed);
+ expect(result?.status).toBe("unsubscribed");
+ // The post-UPDATE re-fetch MUST hit primary so we don't get a stale
+ // 'pending' from the read replica right after our conditional write.
+ expect(calls[calls.length - 1]).toEqual({
+ client: "primary",
+ op: "select",
+ });
+ });
+});
+
+describe("unsubscribeRecipientByToken", () => {
+ it("transitions pending β†’ unsubscribed when no race", async () => {
+ const pending = recipientRow({ status: "pending" });
+ const unsubscribed = recipientRow({
+ status: "unsubscribed",
+ unsubscribed_at: "now",
+ });
+ queueResponses([ok(pending), ok(unsubscribed)]);
+
+ const result = await unsubscribeRecipientByToken("tok-1");
+
+ expect(result).toEqual(unsubscribed);
+ });
+
+ it("transitions confirmed β†’ unsubscribed when no race", async () => {
+ const confirmed = recipientRow({
+ status: "confirmed",
+ confirmed_at: "now",
+ });
+ const unsubscribed = recipientRow({
+ status: "unsubscribed",
+ unsubscribed_at: "now",
+ });
+ queueResponses([ok(confirmed), ok(unsubscribed)]);
+
+ const result = await unsubscribeRecipientByToken("tok-1");
+
+ expect(result).toEqual(unsubscribed);
+ });
+
+ it("returns the row unchanged when already unsubscribed (no UPDATE)", async () => {
+ const unsubscribed = recipientRow({
+ status: "unsubscribed",
+ unsubscribed_at: "now",
+ });
+ queueResponses([ok(unsubscribed)]);
+
+ const result = await unsubscribeRecipientByToken("tok-1");
+
+ expect(result).toEqual(unsubscribed);
+ });
+
+ it("handles a racing unsubscribe by re-fetching the terminal state", async () => {
+ // SELECT sees pending; concurrent caller unsubscribes; our conditional
+ // UPDATE WHERE status != 'unsubscribed' affects 0 rows. Re-fetch
+ // confirms the terminal state.
+ const pending = recipientRow({ status: "pending" });
+ const alreadyUnsub = recipientRow({
+ status: "unsubscribed",
+ unsubscribed_at: "now",
+ });
+ queueResponses([ok(pending), ok(null), ok(alreadyUnsub)]);
+
+ const result = await unsubscribeRecipientByToken("tok-1");
+
+ expect(result).toEqual(alreadyUnsub);
+ expect(calls[calls.length - 1]).toEqual({
+ client: "primary",
+ op: "select",
+ });
+ });
+});
diff --git a/apps/api/src/services/monitoring/email_recipients.ts b/apps/api/src/services/monitoring/email_recipients.ts
new file mode 100644
index 000000000..b46186b98
--- /dev/null
+++ b/apps/api/src/services/monitoring/email_recipients.ts
@@ -0,0 +1,317 @@
+import { randomBytes } from "crypto";
+import { logger as _logger } from "../../lib/logger";
+import { supabase_rr_service, supabase_service } from "../supabase";
+
+const logger = _logger.child({ module: "monitor-email-recipients" });
+
+const POSTGRES_UNIQUE_VIOLATION = "23505";
+
+export type MonitorEmailRecipientStatus =
+ | "pending"
+ | "confirmed"
+ | "unsubscribed";
+
+export type MonitorEmailRecipientSource = "team" | "opt_in" | "legacy";
+
+export type MonitorEmailRecipientRow = {
+ id: string;
+ monitor_id: string;
+ team_id: string;
+ email: string;
+ status: MonitorEmailRecipientStatus;
+ token: string;
+ source: MonitorEmailRecipientSource;
+ confirmation_sent_at: string | null;
+ confirmed_at: string | null;
+ unsubscribed_at: string | null;
+ last_notified_at: string | null;
+ created_at: string;
+ updated_at: string;
+};
+
+export function normalizeRecipientEmail(email: string): string {
+ return email.trim().toLowerCase();
+}
+
+// 32 bytes β†’ 43 chars base64url, no padding. 256 bits of entropy.
+export function generateRecipientToken(): string {
+ return randomBytes(32).toString("base64url");
+}
+
+function throwIfError(error: any, message: string): void {
+ if (error) {
+ throw new Error(`${message}: ${error.message ?? JSON.stringify(error)}`);
+ }
+}
+
+export async function listMonitorEmailRecipients(
+ monitorId: string,
+): Promise<MonitorEmailRecipientRow[]> {
+ const { data, error } = await supabase_rr_service
+ .from("monitor_email_recipients")
+ .select("*")
+ .eq("monitor_id", monitorId);
+
+ throwIfError(error, "Failed to list monitor email recipients");
+ return (data ?? []) as MonitorEmailRecipientRow[];
+}
+
+export async function getRecipientByToken(
+ token: string,
+): Promise<MonitorEmailRecipientRow | null> {
+ const trimmed = token.trim();
+ if (!trimmed) return null;
+
+ const { data, error } = await supabase_rr_service
+ .from("monitor_email_recipients")
+ .select("*")
+ .eq("token", trimmed)
+ .maybeSingle();
+
+ throwIfError(error, "Failed to look up monitor email recipient by token");
+ return (data ?? null) as MonitorEmailRecipientRow | null;
+}
+
+export async function getMonitorNameById(
+ monitorId: string,
+): Promise<string | null> {
+ const { data, error } = await supabase_rr_service
+ .from("monitors")
+ .select("name")
+ .eq("id", monitorId)
+ .maybeSingle();
+
+ if (error) {
+ logger.warn("Failed to load monitor name for opt-in response", {
+ error,
+ monitorId,
+ });
+ return null;
+ }
+ return (data?.name as string | undefined) ?? null;
+}
+
+// Team members are auto-confirmed; they already have dashboard access.
+export async function getTeamMemberEmails(
+ teamId: string,
+ emails: string[],
+): Promise<Set<string>> {
+ if (emails.length === 0) return new Set();
+
+ const { data, error } = await supabase_rr_service
+ .from("user_teams")
+ .select("users(email)")
+ .eq("team_id", teamId);
+
+ if (error) {
+ logger.warn("Failed to load team member emails for recipient sync", {
+ error,
+ teamId,
+ });
+ return new Set();
+ }
+
+ const wanted = new Set(emails.map(normalizeRecipientEmail));
+ const matches = new Set<string>();
+ for (const row of data ?? []) {
+ const email = (row as any).users?.email;
+ if (typeof email === "string") {
+ const normalized = normalizeRecipientEmail(email);
+ if (wanted.has(normalized)) matches.add(normalized);
+ }
+ }
+ return matches;
+}
+
+export type RecipientUpsertInput = {
+ email: string;
+ source: MonitorEmailRecipientSource;
+ status: MonitorEmailRecipientStatus;
+};
+
+export type RecipientUpsertResult = {
+ row: MonitorEmailRecipientRow;
+ created: boolean;
+};
+
+async function fetchRecipientByMonitorEmail(
+ monitorId: string,
+ email: string,
+): Promise<MonitorEmailRecipientRow | null> {
+ const { data, error } = await supabase_rr_service
+ .from("monitor_email_recipients")
+ .select("*")
+ .eq("monitor_id", monitorId)
+ .eq("email", email)
+ .maybeSingle();
+ throwIfError(error, "Failed to look up monitor email recipient");
+ return (data ?? null) as MonitorEmailRecipientRow | null;
+}
+
+// Read replicas can lag behind a freshly-committed INSERT, which is exactly
+// the moment this re-fetch runs (the concurrent writer just won the unique
+// race). Reading from the primary guarantees we see their row.
+async function fetchRecipientByMonitorEmailPrimary(
+ monitorId: string,
+ email: string,
+): Promise<MonitorEmailRecipientRow | null> {
+ const { data, error } = await supabase_service
+ .from("monitor_email_recipients")
+ .select("*")
+ .eq("monitor_id", monitorId)
+ .eq("email", email)
+ .maybeSingle();
+ throwIfError(error, "Failed to look up monitor email recipient");
+ return (data ?? null) as MonitorEmailRecipientRow | null;
+}
+
+// Same rationale as ...Primary above: a conditional UPDATE just landed, so
+// the replica may not have caught up yet when we re-read.
+async function fetchRecipientByIdPrimary(
+ id: string,
+): Promise<MonitorEmailRecipientRow | null> {
+ const { data, error } = await supabase_service
+ .from("monitor_email_recipients")
+ .select("*")
+ .eq("id", id)
+ .maybeSingle();
+ throwIfError(error, "Failed to look up monitor email recipient by id");
+ return (data ?? null) as MonitorEmailRecipientRow | null;
+}
+
+// Idempotent: existing rows are returned unchanged so prior unsubscribe
+// decisions persist across monitor edits. The unique (monitor_id, email)
+// constraint is the source of truth β€” a TOCTOU between the SELECT and the
+// INSERT below is caught via the unique-violation handler so concurrent
+// syncs of the same monitor return the same row instead of 500ing.
+export async function ensureMonitorEmailRecipient(params: {
+ monitorId: string;
+ teamId: string;
+ input: RecipientUpsertInput;
+}): Promise<RecipientUpsertResult> {
+ const email = normalizeRecipientEmail(params.input.email);
+
+ const existing = await fetchRecipientByMonitorEmail(params.monitorId, email);
+ if (existing) {
+ return { row: existing, created: false };
+ }
+
+ const now = new Date().toISOString();
+ const insert = {
+ monitor_id: params.monitorId,
+ team_id: params.teamId,
+ email,
+ status: params.input.status,
+ token: generateRecipientToken(),
+ source: params.input.source,
+ confirmation_sent_at: params.input.status === "pending" ? now : null,
+ confirmed_at: params.input.status === "confirmed" ? now : null,
+ created_at: now,
+ updated_at: now,
+ };
+
+ const { data, error } = await supabase_service
+ .from("monitor_email_recipients")
+ .insert(insert)
+ .select("*")
+ .maybeSingle();
+
+ if (error) {
+ if ((error as { code?: string }).code === POSTGRES_UNIQUE_VIOLATION) {
+ const winner = await fetchRecipientByMonitorEmailPrimary(
+ params.monitorId,
+ email,
+ );
+ if (winner) {
+ return { row: winner, created: false };
+ }
+ }
+ throwIfError(error, "Failed to insert monitor email recipient");
+ }
+
+ return { row: data as MonitorEmailRecipientRow, created: true };
+}
+
+export async function markRecipientConfirmationSent(
+ id: string,
+): Promise<void> {
+ const now = new Date().toISOString();
+ const { error } = await supabase_service
+ .from("monitor_email_recipients")
+ .update({ confirmation_sent_at: now, updated_at: now })
+ .eq("id", id);
+
+ throwIfError(error, "Failed to mark recipient confirmation sent");
+}
+
+export async function confirmRecipientByToken(
+ token: string,
+): Promise<MonitorEmailRecipientRow | null> {
+ const row = await getRecipientByToken(token);
+ if (!row) return null;
+ if (row.status === "confirmed") return row;
+
+ // Unsubscribe is permanent β€” never let a confirm link reverse it.
+ if (row.status === "unsubscribed") return row;
+
+ // Conditional UPDATE: only transition pending β†’ confirmed. If status flips
+ // (e.g. concurrent unsubscribe) between our SELECT and this UPDATE we
+ // affect 0 rows; re-fetch and return the actual current state so an
+ // in-flight confirm can't silently overwrite a terminal unsubscribe.
+ const now = new Date().toISOString();
+ const { data, error } = await supabase_service
+ .from("monitor_email_recipients")
+ .update({ status: "confirmed", confirmed_at: now, updated_at: now })
+ .eq("id", row.id)
+ .eq("status", "pending")
+ .select("*")
+ .maybeSingle();
+
+ throwIfError(error, "Failed to confirm monitor email recipient");
+ if (data) return data as MonitorEmailRecipientRow;
+
+ return await fetchRecipientByIdPrimary(row.id);
+}
+
+export async function unsubscribeRecipientByToken(
+ token: string,
+): Promise<MonitorEmailRecipientRow | null> {
+ const row = await getRecipientByToken(token);
+ if (!row) return null;
+ if (row.status === "unsubscribed") return row;
+
+ // Conditional UPDATE: only writes when the row isn't already unsubscribed,
+ // so two racing unsubscribes don't double-write timestamps. 0 rows here
+ // means a concurrent call beat us to the terminal state.
+ const now = new Date().toISOString();
+ const { data, error } = await supabase_service
+ .from("monitor_email_recipients")
+ .update({ status: "unsubscribed", unsubscribed_at: now, updated_at: now })
+ .eq("id", row.id)
+ .neq("status", "unsubscribed")
+ .select("*")
+ .maybeSingle();
+
+ throwIfError(error, "Failed to unsubscribe monitor email recipient");
+ if (data) return data as MonitorEmailRecipientRow;
+
+ return await fetchRecipientByIdPrimary(row.id);
+}
+
+export async function touchRecipientsNotified(
+ ids: string[],
+): Promise<void> {
+ if (ids.length === 0) return;
+ const now = new Date().toISOString();
+ const { error } = await supabase_service
+ .from("monitor_email_recipients")
+ .update({ last_notified_at: now, updated_at: now })
+ .in("id", ids);
+
+ if (error) {
+ logger.warn("Failed to update last_notified_at on recipients", {
+ error,
+ ids,
+ });
+ }
+}
diff --git a/apps/api/src/services/monitoring/email_recipients_sync.test.ts b/apps/api/src/services/monitoring/email_recipients_sync.test.ts
new file mode 100644
index 000000000..4f38d06a2
--- /dev/null
+++ b/apps/api/src/services/monitoring/email_recipients_sync.test.ts
@@ -0,0 +1,224 @@
+jest.mock("../supabase", () => ({
+ supabase_service: {},
+ supabase_rr_service: {},
+}));
+
+const mockEnsureRecipient = jest.fn();
+const mockListRecipients = jest.fn();
+const mockGetTeamMemberEmails = jest.fn();
+
+jest.mock("./email_recipients", () => {
+ const actual = jest.requireActual("./email_recipients");
+ return {
+ ...actual,
+ ensureMonitorEmailRecipient: (...args: unknown[]) =>
+ mockEnsureRecipient(...args),
+ listMonitorEmailRecipients: (...args: unknown[]) =>
+ mockListRecipients(...args),
+ getTeamMemberEmails: (...args: unknown[]) =>
+ mockGetTeamMemberEmails(...args),
+ };
+});
+
+const mockSendConfirmationEmail = jest.fn();
+jest.mock("../notification/monitoring_email", () => ({
+ sendMonitoringConfirmationEmail: (...args: unknown[]) =>
+ mockSendConfirmationEmail(...args),
+}));
+
+import { syncMonitorEmailRecipients } from "./email_recipients_sync";
+
+beforeEach(() => {
+ mockEnsureRecipient.mockReset();
+ mockListRecipients.mockReset();
+ mockGetTeamMemberEmails.mockReset();
+ mockSendConfirmationEmail.mockReset();
+ mockSendConfirmationEmail.mockResolvedValue({
+ attempted: true,
+ success: true,
+ });
+});
+
+function recipientRow(
+ email: string,
+ status: "pending" | "confirmed" | "unsubscribed",
+ source: "team" | "opt_in" | "legacy",
+) {
+ return {
+ id: `rec-${email}`,
+ monitor_id: "monitor-1",
+ team_id: "team-1",
+ email,
+ status,
+ token: `tok-${email}`,
+ source,
+ confirmation_sent_at: status === "pending" ? new Date().toISOString() : null,
+ confirmed_at: status === "confirmed" ? new Date().toISOString() : null,
+ unsubscribed_at:
+ status === "unsubscribed" ? new Date().toISOString() : null,
+ last_notified_at: null,
+ created_at: new Date().toISOString(),
+ updated_at: new Date().toISOString(),
+ };
+}
+
+function monitor(recipients: string[]): any {
+ return {
+ id: "monitor-1",
+ team_id: "team-1",
+ name: "Test monitor",
+ notification: {
+ email: { enabled: true, recipients },
+ },
+ };
+}
+
+describe("syncMonitorEmailRecipients", () => {
+ it("returns nothing when there are no configured recipients", async () => {
+ const result = await syncMonitorEmailRecipients({
+ monitor: monitor([]),
+ });
+ expect(result.recipients).toEqual([]);
+ expect(mockEnsureRecipient).not.toHaveBeenCalled();
+ });
+
+ it("auto-confirms team members without sending confirmation email", async () => {
+ mockListRecipients.mockResolvedValue([]);
+ mockGetTeamMemberEmails.mockResolvedValue(new Set(["[email protected]"]));
+ mockEnsureRecipient.mockImplementation(async ({ input }) => ({
+ row: recipientRow(input.email, "confirmed", "team"),
+ created: true,
+ }));
+
+ const result = await syncMonitorEmailRecipients({
+ monitor: monitor(["[email protected]"]),
+ });
+
+ expect(mockEnsureRecipient).toHaveBeenCalledWith({
+ monitorId: "monitor-1",
+ teamId: "team-1",
+ input: { email: "[email protected]", source: "team", status: "confirmed" },
+ });
+ expect(mockSendConfirmationEmail).not.toHaveBeenCalled();
+ expect(result.recipients[0]).toMatchObject({
+ email: "[email protected]",
+ status: "confirmed",
+ source: "team",
+ created: true,
+ });
+ });
+
+ it("sends a confirmation email to brand new external recipients", async () => {
+ mockListRecipients.mockResolvedValue([]);
+ mockGetTeamMemberEmails.mockResolvedValue(new Set());
+ mockEnsureRecipient.mockImplementation(async ({ input }) => ({
+ row: recipientRow(input.email, "pending", "opt_in"),
+ created: true,
+ }));
+
+ const result = await syncMonitorEmailRecipients({
+ monitor: monitor(["[email protected]"]),
+ });
+
+ expect(mockEnsureRecipient).toHaveBeenCalledWith({
+ monitorId: "monitor-1",
+ teamId: "team-1",
+ input: {
+ email: "[email protected]",
+ source: "opt_in",
+ status: "pending",
+ },
+ });
+ expect(mockSendConfirmationEmail).toHaveBeenCalledTimes(1);
+ expect(result.recipients[0]).toMatchObject({
+ email: "[email protected]",
+ status: "pending",
+ source: "opt_in",
+ confirmationEmailSent: true,
+ created: true,
+ });
+ });
+
+ it("does not re-send a confirmation email for an existing pending recipient", async () => {
+ mockListRecipients.mockResolvedValue([
+ recipientRow("[email protected]", "pending", "opt_in"),
+ ]);
+ mockGetTeamMemberEmails.mockResolvedValue(new Set());
+
+ const result = await syncMonitorEmailRecipients({
+ monitor: monitor(["[email protected]"]),
+ });
+
+ expect(mockEnsureRecipient).not.toHaveBeenCalled();
+ expect(mockSendConfirmationEmail).not.toHaveBeenCalled();
+ expect(result.recipients[0]).toMatchObject({
+ email: "[email protected]",
+ status: "pending",
+ created: false,
+ });
+ });
+
+ it("preserves prior unsubscribe when the same email is re-added later", async () => {
+ mockListRecipients.mockResolvedValue([
+ recipientRow("[email protected]", "unsubscribed", "opt_in"),
+ ]);
+ mockGetTeamMemberEmails.mockResolvedValue(new Set());
+
+ const result = await syncMonitorEmailRecipients({
+ monitor: monitor(["[email protected]"]),
+ });
+
+ expect(mockEnsureRecipient).not.toHaveBeenCalled();
+ expect(mockSendConfirmationEmail).not.toHaveBeenCalled();
+ expect(result.recipients[0]).toMatchObject({
+ email: "[email protected]",
+ status: "unsubscribed",
+ });
+ });
+
+ it("normalizes emails (lowercases, trims, dedupes) before reconciling", async () => {
+ mockListRecipients.mockResolvedValue([]);
+ mockGetTeamMemberEmails.mockResolvedValue(new Set(["[email protected]"]));
+ mockEnsureRecipient.mockImplementation(async ({ input }) => ({
+ row: recipientRow(input.email, "confirmed", "team"),
+ created: true,
+ }));
+
+ const result = await syncMonitorEmailRecipients({
+ monitor: monitor([
+ ]),
+ });
+
+ expect(mockEnsureRecipient).toHaveBeenCalledTimes(1);
+ expect(result.recipients).toHaveLength(1);
+ expect(result.recipients[0].email).toBe("[email protected]");
+ });
+
+ it("handles a mix of team members and externals in one sync", async () => {
+ mockListRecipients.mockResolvedValue([]);
+ mockGetTeamMemberEmails.mockResolvedValue(new Set(["[email protected]"]));
+ mockEnsureRecipient.mockImplementation(async ({ input }) => ({
+ row: recipientRow(
+ input.email,
+ input.status,
+ input.source,
+ ),
+ created: true,
+ }));
+
+ const result = await syncMonitorEmailRecipients({
+ monitor: monitor(["[email protected]", "[email protected]"]),
+ });
+
+ expect(mockSendConfirmationEmail).toHaveBeenCalledTimes(1);
+ const emailedTo = mockSendConfirmationEmail.mock.calls[0][0].recipient.email;
+ expect(emailedTo).toBe("[email protected]");
+
+ const byEmail = new Map(result.recipients.map(r => [r.email, r]));
+ expect(byEmail.get("[email protected]")?.status).toBe("confirmed");
+ expect(byEmail.get("[email protected]")?.status).toBe("pending");
+ });
+});
diff --git a/apps/api/src/services/monitoring/email_recipients_sync.ts b/apps/api/src/services/monitoring/email_recipients_sync.ts
new file mode 100644
index 000000000..939165752
--- /dev/null
+++ b/apps/api/src/services/monitoring/email_recipients_sync.ts
@@ -0,0 +1,103 @@
+import { logger as _logger } from "../../lib/logger";
+import { sendMonitoringConfirmationEmail } from "../notification/monitoring_email";
+import {
+ ensureMonitorEmailRecipient,
+ getTeamMemberEmails,
+ listMonitorEmailRecipients,
+ normalizeRecipientEmail,
+ type MonitorEmailRecipientRow,
+} from "./email_recipients";
+import type { MonitorRow } from "./types";
+
+const logger = _logger.child({ module: "monitor-email-recipients-sync" });
+
+export type SyncedRecipient = {
+ email: string;
+ status: MonitorEmailRecipientRow["status"];
+ source: MonitorEmailRecipientRow["source"];
+ confirmationEmailSent: boolean;
+ created: boolean;
+};
+
+export type SyncResult = {
+ recipients: SyncedRecipient[];
+};
+
+// Team members β†’ auto-confirmed. External addresses β†’ pending + confirmation
+// email. Existing rows are preserved (so a quick remove-then-re-add doesn't
+// undo a prior unsubscribe or re-send a confirmation).
+export async function syncMonitorEmailRecipients(params: {
+ monitor: MonitorRow;
+}): Promise<SyncResult> {
+ const configured = params.monitor.notification?.email?.recipients ?? [];
+ const normalized = Array.from(
+ new Set(
+ configured
+ .map(normalizeRecipientEmail)
+ .filter(email => email.length > 0),
+ ),
+ );
+
+ if (normalized.length === 0) {
+ return { recipients: [] };
+ }
+
+ const [existingRows, teamMatches] = await Promise.all([
+ listMonitorEmailRecipients(params.monitor.id),
+ getTeamMemberEmails(params.monitor.team_id, normalized),
+ ]);
+ const existingByEmail = new Map(existingRows.map(r => [r.email, r]));
+
+ const results: SyncedRecipient[] = [];
+
+ for (const email of normalized) {
+ const existing = existingByEmail.get(email);
+ if (existing) {
+ results.push({
+ email: existing.email,
+ status: existing.status,
+ source: existing.source,
+ confirmationEmailSent: existing.confirmation_sent_at !== null,
+ created: false,
+ });
+ continue;
+ }
+
+ const isTeamMember = teamMatches.has(email);
+ const { row, created } = await ensureMonitorEmailRecipient({
+ monitorId: params.monitor.id,
+ teamId: params.monitor.team_id,
+ input: {
+ email,
+ source: isTeamMember ? "team" : "opt_in",
+ status: isTeamMember ? "confirmed" : "pending",
+ },
+ });
+
+ let confirmationEmailSent = false;
+ if (created && !isTeamMember && row.status === "pending") {
+ const sendResult = await sendMonitoringConfirmationEmail({
+ recipient: row,
+ monitorName: params.monitor.name,
+ }).catch(error => {
+ logger.warn("Confirmation email send threw", {
+ error,
+ recipientId: row.id,
+ monitorId: params.monitor.id,
+ });
+ return { attempted: true, success: false } as const;
+ });
+ confirmationEmailSent = sendResult.attempted && sendResult.success;
+ }
+
+ results.push({
+ email: row.email,
+ status: row.status,
+ source: row.source,
+ confirmationEmailSent,
+ created,
+ });
+ }
+
+ return { recipients: results };
+}
diff --git a/apps/api/src/services/notification/monitoring_email.test.ts b/apps/api/src/services/notification/monitoring_email.test.ts
index 22877e0a8..a568abf0d 100644
--- a/apps/api/src/services/notification/monitoring_email.test.ts
+++ b/apps/api/src/services/notification/monitoring_email.test.ts
@@ -1,21 +1,86 @@
jest.mock("../supabase", () => ({
supabase_service: {},
+ supabase_rr_service: {},
}));
+const mockEnsureRecipient = jest.fn();
+const mockListRecipients = jest.fn();
+const mockTouchNotified = jest.fn();
+const mockMarkConfirmationSent = jest.fn();
+
+jest.mock("../monitoring/email_recipients", () => {
+ const actual = jest.requireActual("../monitoring/email_recipients");
+ return {
+ ...actual,
+ ensureMonitorEmailRecipient: (...args: unknown[]) =>
+ mockEnsureRecipient(...args),
+ listMonitorEmailRecipients: (...args: unknown[]) =>
+ mockListRecipients(...args),
+ touchRecipientsNotified: (...args: unknown[]) => mockTouchNotified(...args),
+ markRecipientConfirmationSent: (...args: unknown[]) =>
+ mockMarkConfirmationSent(...args),
+ };
+});
+
+const mockResendSend = jest.fn();
jest.mock("resend", () => ({
Resend: jest.fn().mockImplementation(() => ({
- emails: { send: jest.fn() },
+ emails: { send: mockResendSend },
})),
}));
import {
+ buildConfirmationHtml,
buildHtml,
buildMonitoringCheckDashboardUrl,
+ buildRecipientConfirmationUrl,
+ buildRecipientUnsubscribeUrl,
+ sendMonitoringConfirmationEmail,
sendMonitoringEmailSummary,
type MonitoringEmailPayload,
} from "./monitoring_email";
-describe("monitoring email", () => {
+beforeEach(() => {
+ mockEnsureRecipient.mockReset();
+ mockListRecipients.mockReset();
+ mockTouchNotified.mockReset();
+ mockMarkConfirmationSent.mockReset();
+ mockResendSend.mockReset();
+ mockResendSend.mockResolvedValue({ data: { id: "msg-1" }, error: null });
+ mockTouchNotified.mockResolvedValue(undefined);
+ mockMarkConfirmationSent.mockResolvedValue(undefined);
+ process.env.RESEND_API_KEY = "test-key";
+});
+
+afterAll(() => {
+ delete process.env.RESEND_API_KEY;
+});
+
+function fakeRecipient(
+ email: string,
+ status: "pending" | "confirmed" | "unsubscribed",
+ source: "team" | "opt_in" | "legacy" = "opt_in",
+) {
+ const sanitized = email.replace(/[^a-z0-9]/gi, "");
+ return {
+ id: `rec-${sanitized}`,
+ monitor_id: "monitor-1",
+ team_id: "team-1",
+ email,
+ status,
+ token: `tok-${sanitized}`,
+ source,
+ confirmation_sent_at: status === "pending" ? new Date().toISOString() : null,
+ confirmed_at: status === "confirmed" ? new Date().toISOString() : null,
+ unsubscribed_at:
+ status === "unsubscribed" ? new Date().toISOString() : null,
+ last_notified_at: null,
+ created_at: new Date().toISOString(),
+ updated_at: new Date().toISOString(),
+ };
+}
+
+describe("monitoring email URLs", () => {
it("builds a dashboard link for a monitor check", () => {
expect(
buildMonitoringCheckDashboardUrl(
@@ -30,7 +95,19 @@ describe("monitoring email", () => {
);
});
- it("includes the dashboard check link in the email html", () => {
+ it("builds opt-in and unsubscribe URLs against the dashboard base", () => {
+ const confirm = buildRecipientConfirmationUrl("abc123");
+ expect(confirm).toContain("/monitoring/email/confirm");
+ expect(confirm).not.toContain("/v2/");
+ expect(confirm).toContain("token=abc123");
+
+ const unsub = buildRecipientUnsubscribeUrl("abc123");
+ expect(unsub).toContain("/monitoring/email/unsubscribe");
+ expect(unsub).not.toContain("/v2/");
+ expect(unsub).toContain("token=abc123");
+ });
+
+ it("includes the dashboard check link and unsubscribe footer in the email html", () => {
const dashboardUrl = buildMonitoringCheckDashboardUrl(
{
monitorId: "monitor-1",
@@ -57,55 +134,144 @@ describe("monitoring email", () => {
},
],
creditsUsed: 1,
+ unsubscribeUrl:
+ "https://www.firecrawl.dev/monitoring/email/unsubscribe?token=tok123",
};
- expect(buildHtml(payload)).toContain(
+ const html = buildHtml(payload);
+ expect(html).toContain(
`<a href="${dashboardUrl}">View this check in the dashboard</a>`,
);
+ expect(html).toContain(
+ "https://www.firecrawl.dev/monitoring/email/unsubscribe?token=tok123",
+ );
+ expect(html).toContain("Unsubscribe from this monitor");
+ });
+
+ it("omits the unsubscribe footer when no unsubscribe URL is provided", () => {
+ const html = buildHtml({
+ monitorId: "m1",
+ monitorName: "M",
+ checkId: "c1",
+ dashboardUrl: "https://www.firecrawl.dev/app/monitoring/m1?checkId=c1",
+ summary: { changed: 0, new: 1, removed: 0, error: 0, totalPages: 1 },
+ pages: [{ url: "https://example.com", status: "new" }],
+ creditsUsed: 1,
+ });
+ expect(html).not.toContain("Unsubscribe from this monitor");
});
+});
- describe("sendMonitoringEmailSummary β€” judgment gating", () => {
- function buildArgs(opts: {
- goal?: string | null;
- emailEnabled?: boolean;
- pages: Array<{
- status: string;
- meaningful?: boolean | null;
- }>;
- }) {
- return {
- monitor: {
- id: "monitor-1",
- team_id: "team-1",
- name: "Test",
- goal: opts.goal ?? null,
- judge_enabled: Boolean(opts.goal),
- notification: opts.emailEnabled
- ? { email: { enabled: true, recipients: ["[email protected]"] } }
- : null,
- } as any,
- check: {
- id: "check-1",
- changed_count: opts.pages.filter(p => p.status === "changed").length,
- new_count: opts.pages.filter(p => p.status === "new").length,
- removed_count: opts.pages.filter(p => p.status === "removed").length,
- error_count: opts.pages.filter(p => p.status === "error").length,
- } as any,
- pages: opts.pages.map((p, i) => ({
- url: `https://example.com/${i}`,
- status: p.status,
- judgment:
- p.meaningful === null || p.meaningful === undefined
- ? null
- : {
- meaningful: p.meaningful,
- confidence: "high" as const,
- reason: "test",
- fields: [],
- },
- })),
- };
- }
+describe("buildConfirmationHtml", () => {
+ it("renders a confirm CTA and a fallback unsubscribe link", () => {
+ const html = buildConfirmationHtml({
+ monitorName: "Marketing site",
+ recipientEmail: "[email protected]",
+ confirmUrl:
+ "https://www.firecrawl.dev/monitoring/email/confirm?token=tok1",
+ unsubscribeUrl:
+ "https://www.firecrawl.dev/monitoring/email/unsubscribe?token=tok1",
+ });
+ expect(html).toContain("Confirm subscription");
+ expect(html).toContain("Marketing site");
+ expect(html).toContain("[email protected]");
+ expect(html).toContain("token=tok1");
+ });
+
+ it("escapes HTML in recipient and monitor names", () => {
+ const html = buildConfirmationHtml({
+ monitorName: "<script>x</script>",
+ recipientEmail: "[email protected]",
+ confirmUrl: "https://example.com/c?token=t",
+ unsubscribeUrl: "https://example.com/u?token=t",
+ });
+ expect(html).not.toContain("<script>x</script>");
+ expect(html).toContain("&lt;script&gt;");
+ });
+});
+
+describe("sendMonitoringConfirmationEmail", () => {
+ it("sends a Resend email and marks confirmation_sent_at", async () => {
+ const result = await sendMonitoringConfirmationEmail({
+ recipient: fakeRecipient("[email protected]", "pending"),
+ monitorName: "My monitor",
+ });
+ expect(result).toEqual({ attempted: true, success: true });
+ expect(mockResendSend).toHaveBeenCalledTimes(1);
+ expect(mockResendSend.mock.calls[0][0].to).toBe("[email protected]");
+ expect(mockResendSend.mock.calls[0][0].subject).toContain(
+ 'Confirm subscription',
+ );
+ expect(mockMarkConfirmationSent).toHaveBeenCalledWith("rec-newexamplecom");
+ });
+
+ it("returns failure if Resend reports an error", async () => {
+ mockResendSend.mockResolvedValueOnce({ data: null, error: "boom" });
+ const result = await sendMonitoringConfirmationEmail({
+ recipient: fakeRecipient("[email protected]", "pending"),
+ monitorName: "My monitor",
+ });
+ expect(result.attempted).toBe(true);
+ expect(result.success).toBe(false);
+ expect(mockMarkConfirmationSent).not.toHaveBeenCalled();
+ });
+});
+
+describe("sendMonitoringEmailSummary", () => {
+ function buildArgs(opts: {
+ goal?: string | null;
+ emailEnabled?: boolean;
+ recipients?: string[];
+ pages: Array<{
+ status: string;
+ meaningful?: boolean | null;
+ }>;
+ }) {
+ return {
+ monitor: {
+ id: "monitor-1",
+ team_id: "team-1",
+ name: "Test",
+ goal: opts.goal ?? null,
+ judge_enabled: Boolean(opts.goal),
+ notification: opts.emailEnabled
+ ? {
+ email: {
+ enabled: true,
+ recipients: opts.recipients ?? ["[email protected]"],
+ },
+ }
+ : null,
+ } as any,
+ check: {
+ id: "check-1",
+ changed_count: opts.pages.filter(p => p.status === "changed").length,
+ new_count: opts.pages.filter(p => p.status === "new").length,
+ removed_count: opts.pages.filter(p => p.status === "removed").length,
+ error_count: opts.pages.filter(p => p.status === "error").length,
+ } as any,
+ pages: opts.pages.map((p, i) => ({
+ url: `https://example.com/${i}`,
+ status: p.status,
+ judgment:
+ p.meaningful === null || p.meaningful === undefined
+ ? null
+ : {
+ meaningful: p.meaningful,
+ confidence: "high" as const,
+ reason: "test",
+ fields: [],
+ },
+ })),
+ };
+ }
+
+ describe("judgment gating", () => {
+ beforeEach(() => {
+ mockListRecipients.mockResolvedValue([
+ fakeRecipient("[email protected]", "confirmed"),
+ ]);
+ });
it("suppresses email when goal set and all changed pages are noise", async () => {
const result = await sendMonitoringEmailSummary(
@@ -182,4 +348,112 @@ describe("monitoring email", () => {
expect(result.attempted).toBe(true);
});
});
+
+ describe("opt-in gating", () => {
+ it("skips entirely when no recipients have confirmed", async () => {
+ mockListRecipients.mockResolvedValue([
+ fakeRecipient("[email protected]", "pending"),
+ ]);
+ const result = await sendMonitoringEmailSummary(
+ buildArgs({
+ emailEnabled: true,
+ recipients: ["[email protected]"],
+ pages: [{ status: "changed" }],
+ }),
+ );
+ expect(result.attempted).toBe(false);
+ expect(result.recipients).toEqual([]);
+ expect(result.pendingRecipients).toBe(1);
+ expect(mockResendSend).not.toHaveBeenCalled();
+ });
+
+ it("skips unsubscribed recipients but emails confirmed ones", async () => {
+ mockListRecipients.mockResolvedValue([
+ fakeRecipient("[email protected]", "confirmed"),
+ fakeRecipient("[email protected]", "unsubscribed"),
+ ]);
+ const result = await sendMonitoringEmailSummary(
+ buildArgs({
+ emailEnabled: true,
+ pages: [{ status: "changed" }],
+ }),
+ );
+ expect(result.attempted).toBe(true);
+ expect(result.recipients).toEqual(["[email protected]"]);
+ expect(result.unsubscribedRecipients).toBe(1);
+ expect(mockResendSend).toHaveBeenCalledTimes(1);
+ expect(mockResendSend.mock.calls[0][0].to).toBe("[email protected]");
+ });
+
+ it("sends one email per recipient with a unique unsubscribe link", async () => {
+ mockListRecipients.mockResolvedValue([
+ fakeRecipient("[email protected]", "confirmed"),
+ fakeRecipient("[email protected]", "confirmed"),
+ ]);
+ const result = await sendMonitoringEmailSummary(
+ buildArgs({
+ emailEnabled: true,
+ pages: [{ status: "changed" }],
+ }),
+ );
+ expect(result.attempted).toBe(true);
+ expect(mockResendSend).toHaveBeenCalledTimes(2);
+ const calls = mockResendSend.mock.calls.map(c => c[0]);
+ const aCall = calls.find(c => c.to === "[email protected]");
+ const bCall = calls.find(c => c.to === "[email protected]");
+ expect(aCall.html).toContain("token=tok-aexamplecom");
+ expect(bCall.html).toContain("token=tok-bexamplecom");
+ expect(aCall.html).not.toContain("token=tok-bexamplecom");
+ expect(mockTouchNotified).toHaveBeenCalledWith([
+ "rec-aexamplecom",
+ "rec-bexamplecom",
+ ]);
+ });
+
+ it("bootstraps legacy monitors when recipient rows are entirely missing", async () => {
+ mockListRecipients.mockResolvedValue([]);
+ mockEnsureRecipient.mockResolvedValue({
+ created: true,
+ row: fakeRecipient("[email protected]", "confirmed", "legacy"),
+ });
+
+ const result = await sendMonitoringEmailSummary(
+ buildArgs({
+ emailEnabled: true,
+ recipients: ["[email protected]"],
+ pages: [{ status: "changed" }],
+ }),
+ );
+ expect(result.attempted).toBe(true);
+ expect(result.recipients).toEqual(["[email protected]"]);
+ expect(mockEnsureRecipient).toHaveBeenCalledWith({
+ monitorId: "monitor-1",
+ teamId: "team-1",
+ input: {
+ email: "[email protected]",
+ source: "legacy",
+ status: "confirmed",
+ },
+ });
+ });
+
+ it("treats missing recipients as pending when rows are partially present", async () => {
+ mockListRecipients.mockResolvedValue([
+ fakeRecipient("[email protected]", "confirmed"),
+ ]);
+ const result = await sendMonitoringEmailSummary(
+ buildArgs({
+ emailEnabled: true,
+ pages: [{ status: "changed" }],
+ }),
+ );
+ expect(result.attempted).toBe(true);
+ expect(result.recipients).toEqual(["[email protected]"]);
+ expect(result.pendingRecipients).toBe(1);
+ expect(mockEnsureRecipient).not.toHaveBeenCalled();
+ });
+ });
});
diff --git a/apps/api/src/services/notification/monitoring_email.ts b/apps/api/src/services/notification/monitoring_email.ts
index 2670879a5..7b8a8a446 100644
--- a/apps/api/src/services/notification/monitoring_email.ts
+++ b/apps/api/src/services/notification/monitoring_email.ts
@@ -4,9 +4,20 @@ import { config } from "../../config";
import { logger as _logger } from "../../lib/logger";
import { supabase_service } from "../supabase";
import type { MonitorCheckRow, MonitorRow } from "../monitoring/types";
+import {
+ ensureMonitorEmailRecipient,
+ listMonitorEmailRecipients,
+ markRecipientConfirmationSent,
+ normalizeRecipientEmail,
+ touchRecipientsNotified,
+ type MonitorEmailRecipientRow,
+} from "../monitoring/email_recipients";
const logger = _logger.child({ module: "monitoring-email" });
+const FROM_ADDRESS = "Firecrawl <[email protected]>";
+const REPLY_TO_ADDRESS = "[email protected]";
+
type MonitoringEmailPage = {
url: string;
status: string;
@@ -72,6 +83,8 @@ export type MonitoringEmailPayload = {
};
pages: MonitoringEmailPage[];
creditsUsed: number | null;
+ // When omitted, the footer drops the unsubscribe row.
+ unsubscribeUrl?: string;
};
async function getTeamEmails(teamId: string): Promise<string[]> {
@@ -122,6 +135,33 @@ export function buildMonitoringCheckDashboardUrl(
return url.toString();
}
+function buildPublicWebUrl(path: string, token: string): string {
+ const base = config.FIRECRAWL_DASHBOARD_URL.trim();
+ const url = new URL(path, base);
+ url.searchParams.set("token", token);
+ return url.toString();
+}
+
+// Email links land on the firecrawl-web pages, which POST the token to the
+// API. Keeps branding consistent and stops passive link scanners (Outlook
+// Safe Links, etc.) from accidentally consuming tokens with bare GETs.
+export function buildRecipientConfirmationUrl(token: string): string {
+ return buildPublicWebUrl("/monitoring/email/confirm", token);
+}
+
+export function buildRecipientUnsubscribeUrl(token: string): string {
+ return buildPublicWebUrl("/monitoring/email/unsubscribe", token);
+}
+
+function buildUnsubscribeFooter(unsubscribeUrl: string): string {
+ const safe = escapeHtml(unsubscribeUrl);
+ return `<hr style="border:none;border-top:1px solid #e5e7eb;margin:24px 0 12px;" />
+<p style="color:#6b7280;font-size:12px;line-height:1.6;margin:0;">
+You're receiving this because you opted in to Firecrawl monitor alerts at this address.
+<a href="${safe}" style="color:#6b7280;text-decoration:underline;">Unsubscribe from this monitor</a>.
+</p>`;
+}
+
export function buildHtml(payload: MonitoringEmailPayload): string {
const sortedPages = [...payload.pages].sort((a, b) => {
const aMeaningful = a.judgment?.meaningful === true ? 0 : 1;
@@ -179,9 +219,216 @@ ${pageItems ? `<p>Top pages:</p><ul>${pageItems}</ul>` : ""}
<p><a href="${dashboardUrl}">View this check in the dashboard</a></p>
<p>Check ID: <code>${escapeHtml(payload.checkId)}</code></p>
<p>Credits used: ${payload.creditsUsed ?? "unknown"}</p>
+<br/>Thanks,<br/>Firecrawl Team<br/>
+${payload.unsubscribeUrl ? buildUnsubscribeFooter(payload.unsubscribeUrl) : ""}`;
+}
+
+export function buildConfirmationHtml(params: {
+ monitorName: string;
+ recipientEmail: string;
+ confirmUrl: string;
+ unsubscribeUrl: string;
+}): string {
+ const monitorName = escapeHtml(params.monitorName);
+ const recipientEmail = escapeHtml(params.recipientEmail);
+ const confirmUrl = escapeHtml(params.confirmUrl);
+ const unsubscribeUrl = escapeHtml(params.unsubscribeUrl);
+
+ return `Hey there,<br/>
+<p>A Firecrawl user added <strong>${recipientEmail}</strong> as a notification recipient for the monitor <strong>${monitorName}</strong>.</p>
+<p>If you'd like to receive change-detection emails for this monitor, please confirm:</p>
+<p style="margin:24px 0;">
+ <a href="${confirmUrl}"
+ style="display:inline-block;padding:10px 18px;background:#fa5d19;color:#ffffff;text-decoration:none;border-radius:8px;font-weight:600;">
+ Confirm subscription
+ </a>
+</p>
+<p style="color:#6b7280;font-size:13px;line-height:1.6;">
+ If that button doesn't work, copy and paste this link into your browser:<br/>
+ <a href="${confirmUrl}" style="color:#fa5d19;word-break:break-all;">${confirmUrl}</a>
+</p>
+<p style="color:#6b7280;font-size:13px;line-height:1.6;">
+ You will not receive any monitor notifications at this address until you click the link above. If you didn't expect this email you can safely ignore it, or
+ <a href="${unsubscribeUrl}" style="color:#6b7280;text-decoration:underline;">block all future emails from this monitor</a>.
+</p>
<br/>Thanks,<br/>Firecrawl Team<br/>`;
}
+function getResendClient(): Resend | null {
+ const key = config.RESEND_API_KEY?.trim();
+ if (!key) return null;
+ return new Resend(key);
+}
+
+export async function sendMonitoringConfirmationEmail(params: {
+ recipient: MonitorEmailRecipientRow;
+ monitorName: string;
+}): Promise<{ attempted: boolean; success: boolean; error?: string }> {
+ const resend = getResendClient();
+ if (!resend) {
+ logger.warn(
+ "Skipping monitor opt-in email; RESEND_API_KEY is not set",
+ {
+ monitorId: params.recipient.monitor_id,
+ recipientId: params.recipient.id,
+ },
+ );
+ return { attempted: false, success: true };
+ }
+
+ const confirmUrl = buildRecipientConfirmationUrl(params.recipient.token);
+ const unsubscribeUrl = buildRecipientUnsubscribeUrl(params.recipient.token);
+ const html = buildConfirmationHtml({
+ monitorName: params.monitorName,
+ recipientEmail: params.recipient.email,
+ confirmUrl,
+ unsubscribeUrl,
+ });
+
+ try {
+ const { error } = await resend.emails.send({
+ from: FROM_ADDRESS,
+ to: params.recipient.email,
+ reply_to: REPLY_TO_ADDRESS,
+ subject: `Confirm subscription: Firecrawl monitor "${params.monitorName}"`,
+ html,
+ });
+
+ if (error) {
+ logger.warn("Failed to send monitor confirmation email", {
+ error,
+ recipientId: params.recipient.id,
+ monitorId: params.recipient.monitor_id,
+ });
+ return {
+ attempted: true,
+ success: false,
+ error: typeof error === "string" ? error : JSON.stringify(error),
+ };
+ }
+
+ await markRecipientConfirmationSent(params.recipient.id);
+ logger.info("Sent monitor confirmation email", {
+ recipientId: params.recipient.id,
+ monitorId: params.recipient.monitor_id,
+ });
+ return { attempted: true, success: true };
+ } catch (error) {
+ logger.warn("Exception sending monitor confirmation email", {
+ error,
+ recipientId: params.recipient.id,
+ });
+ return {
+ attempted: true,
+ success: false,
+ error: error instanceof Error ? error.message : String(error),
+ };
+ }
+}
+
+type ResolvedRecipients = {
+ confirmedRecipients: MonitorEmailRecipientRow[];
+ pending: number;
+ unsubscribed: number;
+ total: number;
+};
+
+async function resolveSendableRecipients(
+ monitor: MonitorRow,
+): Promise<ResolvedRecipients> {
+ const configEmail = monitor.notification?.email;
+ const explicitConfigured = Array.isArray(configEmail?.recipients)
+ ? (configEmail!.recipients as string[])
+ .map(normalizeRecipientEmail)
+ .filter(Boolean)
+ : [];
+
+ if (explicitConfigured.length > 0) {
+ let rows = await listMonitorEmailRecipients(monitor.id);
+
+ // Legacy monitors (configured pre-opt-in) have zero rows; bootstrap them
+ // as confirmed so existing alerts keep flowing without a DB backfill.
+ // Partial-row monitors keep strict gating β€” missing addresses stay
+ // pending rather than getting auto-confirmed.
+ if (rows.length === 0) {
+ const legacyRows = await Promise.all(
+ explicitConfigured.map(async email => {
+ const { row } = await ensureMonitorEmailRecipient({
+ monitorId: monitor.id,
+ teamId: monitor.team_id,
+ input: {
+ email,
+ source: "legacy",
+ status: "confirmed",
+ },
+ });
+ return row;
+ }),
+ );
+ rows = legacyRows;
+ logger.info("Bootstrapped legacy monitor recipients without DB backfill", {
+ monitorId: monitor.id,
+ recipients: explicitConfigured,
+ });
+ }
+
+ const rowsByEmail = new Map(rows.map(r => [r.email, r]));
+
+ const confirmedRecipients: MonitorEmailRecipientRow[] = [];
+ let pending = 0;
+ let unsubscribed = 0;
+
+ for (const email of explicitConfigured) {
+ const row = rowsByEmail.get(email);
+ if (!row) {
+ // Recipient appears in JSONB but has no opt-in row β€” treat as
+ // pending so we never send without an explicit record.
+ pending += 1;
+ continue;
+ }
+ if (row.status === "confirmed") {
+ confirmedRecipients.push(row);
+ } else if (row.status === "unsubscribed") {
+ unsubscribed += 1;
+ } else {
+ pending += 1;
+ }
+ }
+
+ return {
+ confirmedRecipients,
+ pending,
+ unsubscribed,
+ total: explicitConfigured.length,
+ };
+ }
+
+ // Fallback: team members (auto-confirmed; getTeamEmails still applies
+ // their global notification_preferences).
+ const teamEmails = await getTeamEmails(monitor.team_id);
+ const syntheticRows: MonitorEmailRecipientRow[] = await Promise.all(
+ teamEmails.map(async email => {
+ const { row } = await ensureMonitorEmailRecipient({
+ monitorId: monitor.id,
+ teamId: monitor.team_id,
+ input: {
+ email,
+ source: "team",
+ status: "confirmed",
+ },
+ });
+ return row;
+ }),
+ );
+
+ return {
+ confirmedRecipients: syntheticRows.filter(r => r.status === "confirmed"),
+ pending: 0,
+ unsubscribed: syntheticRows.filter(r => r.status === "unsubscribed").length,
+ total: teamEmails.length,
+ };
+}
+
export async function sendMonitoringEmailSummary(params: {
monitor: MonitorRow;
check: MonitorCheckRow;
@@ -190,6 +437,8 @@ export async function sendMonitoringEmailSummary(params: {
attempted: boolean;
success: boolean;
recipients: string[];
+ pendingRecipients?: number;
+ unsubscribedRecipients?: number;
error?: string;
}> {
const configEmail = params.monitor.notification?.email;
@@ -222,9 +471,8 @@ export async function sendMonitoringEmailSummary(params: {
return { attempted: false, success: true, recipients: [] };
}
- // Caller may pass a paginated subset; only trust the judgment-based
- // suppression when changedPages covers the full changed_count. A missed
- // meaningful alert is worse than an extra noisy email.
+ // Trust judgment-based suppression only when the changed page list is
+ // complete (a missed meaningful alert is worse than a noisy one).
if (params.monitor.judge_enabled && params.monitor.goal) {
const changedPages = params.pages.filter(p => p.status === "changed");
const nonChangedActivity = params.pages.some(
@@ -264,91 +512,147 @@ export async function sendMonitoringEmailSummary(params: {
}
}
- const explicitRecipients = configEmail.recipients ?? [];
- const teamRecipients =
- explicitRecipients.length > 0
- ? []
- : await getTeamEmails(params.monitor.team_id);
- const recipients = [...new Set([...explicitRecipients, ...teamRecipients])];
- if (recipients.length === 0) {
- logger.info("Skipping monitoring email summary; no recipients configured", {
- monitorId: params.monitor.id,
- checkId: params.check.id,
- });
- return { attempted: false, success: true, recipients };
+ const resolved = await resolveSendableRecipients(params.monitor);
+ if (resolved.confirmedRecipients.length === 0) {
+ logger.info(
+ "Skipping monitoring email summary; no confirmed recipients",
+ {
+ monitorId: params.monitor.id,
+ checkId: params.check.id,
+ configured: resolved.total,
+ pending: resolved.pending,
+ unsubscribed: resolved.unsubscribed,
+ },
+ );
+ return {
+ attempted: false,
+ success: true,
+ recipients: [],
+ pendingRecipients: resolved.pending,
+ unsubscribedRecipients: resolved.unsubscribed,
+ };
}
- const resendApiKey = config.RESEND_API_KEY?.trim();
- if (!resendApiKey) {
+ const resend = getResendClient();
+ if (!resend) {
logger.warn(
"Skipping monitoring email summary; RESEND_API_KEY is not set",
{
monitorId: params.monitor.id,
checkId: params.check.id,
- recipients,
+ recipients: resolved.confirmedRecipients.map(r => r.email),
},
);
- return { attempted: false, success: true, recipients };
+ return {
+ attempted: false,
+ success: true,
+ recipients: resolved.confirmedRecipients.map(r => r.email),
+ pendingRecipients: resolved.pending,
+ unsubscribedRecipients: resolved.unsubscribed,
+ };
}
- const payload: MonitoringEmailPayload = {
+ const dashboardUrl = buildMonitoringCheckDashboardUrl({
monitorId: params.monitor.id,
- monitorName: params.monitor.name,
checkId: params.check.id,
- dashboardUrl: buildMonitoringCheckDashboardUrl({
- monitorId: params.monitor.id,
- checkId: params.check.id,
- }),
- summary: {
- changed: params.check.changed_count,
- new: params.check.new_count,
- removed: params.check.removed_count,
- error: params.check.error_count,
- totalPages: params.check.total_pages,
- },
- pages: params.pages,
- creditsUsed: params.check.actual_credits,
- };
-
- const resend = new Resend(resendApiKey);
- try {
- const { error } = await resend.emails.send({
- from: "Firecrawl <[email protected]>",
- to: recipients,
- reply_to: "[email protected]",
- subject: `Monitor changes detected: ${params.monitor.name}`,
- html: buildHtml(payload),
- });
+ });
- if (error) {
- logger.warn("Monitoring email summary send failed", {
+ // One email per recipient: unique unsubscribe links + no recipient leakage.
+ const sendResults = await Promise.all(
+ resolved.confirmedRecipients.map(async recipient => {
+ const payload: MonitoringEmailPayload = {
monitorId: params.monitor.id,
+ monitorName: params.monitor.name,
checkId: params.check.id,
- recipients,
- error,
- });
- return {
- attempted: true,
- success: false,
- recipients,
- error: typeof error === "string" ? error : JSON.stringify(error),
+ dashboardUrl,
+ summary: {
+ changed: params.check.changed_count,
+ new: params.check.new_count,
+ removed: params.check.removed_count,
+ error: params.check.error_count,
+ totalPages: params.check.total_pages,
+ },
+ pages: params.pages,
+ creditsUsed: params.check.actual_credits,
+ unsubscribeUrl: buildRecipientUnsubscribeUrl(recipient.token),
};
- }
- logger.info("Monitoring email summary sent", {
+ try {
+ const { error } = await resend.emails.send({
+ from: FROM_ADDRESS,
+ to: recipient.email,
+ reply_to: REPLY_TO_ADDRESS,
+ subject: `Monitor changes detected: ${params.monitor.name}`,
+ html: buildHtml(payload),
+ });
+ if (error) {
+ return {
+ recipient,
+ success: false,
+ error:
+ typeof error === "string" ? error : JSON.stringify(error),
+ };
+ }
+ return { recipient, success: true };
+ } catch (error) {
+ return {
+ recipient,
+ success: false,
+ error: error instanceof Error ? error.message : String(error),
+ };
+ }
+ }),
+ );
+
+ const succeededIds = sendResults
+ .filter(r => r.success)
+ .map(r => r.recipient.id);
+ const failures = sendResults.filter(r => !r.success);
+ const allRecipientEmails = resolved.confirmedRecipients.map(r => r.email);
+
+ if (succeededIds.length > 0) {
+ await touchRecipientsNotified(succeededIds);
+ }
+
+ if (failures.length === allRecipientEmails.length) {
+ const errorSummary = failures
+ .map(f => `${f.recipient.email}: ${f.error}`)
+ .join("; ");
+ logger.warn("Monitor email summary failed for all recipients", {
monitorId: params.monitor.id,
checkId: params.check.id,
- recipients,
+ failures: errorSummary,
});
-
- return { attempted: true, success: true, recipients };
- } catch (error) {
- logger.warn("Failed to send monitoring email summary", { error });
return {
attempted: true,
success: false,
- recipients,
- error: error instanceof Error ? error.message : String(error),
+ recipients: allRecipientEmails,
+ pendingRecipients: resolved.pending,
+ unsubscribedRecipients: resolved.unsubscribed,
+ error: errorSummary,
};
}
+
+ if (failures.length > 0) {
+ logger.warn("Monitor email summary partially failed", {
+ monitorId: params.monitor.id,
+ checkId: params.check.id,
+ delivered: succeededIds.length,
+ failed: failures.length,
+ });
+ } else {
+ logger.info("Monitor email summary sent", {
+ monitorId: params.monitor.id,
+ checkId: params.check.id,
+ recipients: allRecipientEmails,
+ });
+ }
+
+ return {
+ attempted: true,
+ success: true,
+ recipients: allRecipientEmails,
+ pendingRecipients: resolved.pending,
+ unsubscribedRecipients: resolved.unsubscribed,
+ };
}
diff --git a/apps/js-sdk/firecrawl/src/v2/types.ts b/apps/js-sdk/firecrawl/src/v2/types.ts
index 6709fd0e1..863c9b72e 100644
--- a/apps/js-sdk/firecrawl/src/v2/types.ts
+++ b/apps/js-sdk/firecrawl/src/v2/types.ts
@@ -660,6 +660,25 @@ export interface MonitorEmailNotification {
includeDiffs?: boolean;
}
+/**
+ * Per-recipient opt-in state for monitor email notifications.
+ *
+ * External recipients (not members of the team that owns the monitor) must
+ * confirm their subscription via a one-time email before they receive any
+ * monitor notifications. Team members are auto-confirmed.
+ *
+ * - `pending` β†’ confirmation email sent, no notifications yet
+ * - `confirmed` β†’ notifications enabled
+ * - `unsubscribed` β†’ recipient opted out and cannot be re-added without a new
+ * confirmation flow
+ */
+export interface MonitorEmailRecipientSubscription {
+ email: string;
+ status: "pending" | "confirmed" | "unsubscribed";
+ source: "team" | "opt_in" | "legacy";
+ confirmationEmailSent?: boolean;
+}
+
export interface MonitorNotification {
email?: MonitorEmailNotification;
}
@@ -731,6 +750,13 @@ export interface Monitor {
targets: MonitorTarget[];
webhook?: MonitorWebhookConfig | null;
notification?: MonitorNotification | null;
+ /**
+ * Present on create/update/get responses. Reflects the opt-in state of every
+ * email recipient currently configured on the monitor. Absent when the API
+ * has not reconciled recipients (e.g. team-default delivery with no
+ * explicit recipients).
+ */
+ emailRecipientSubscriptions?: MonitorEmailRecipientSubscription[];
retentionDays: number;
estimatedCreditsPerMonth?: number | null;
lastCheckSummary?: MonitorSummary | null;
diff --git a/apps/python-sdk/firecrawl/v2/types.py b/apps/python-sdk/firecrawl/v2/types.py
index 41965c01a..aef032208 100644
--- a/apps/python-sdk/firecrawl/v2/types.py
+++ b/apps/python-sdk/firecrawl/v2/types.py
@@ -874,6 +874,30 @@ class MonitorNotification(BaseModel):
email: Optional[MonitorEmailNotification] = None
+class MonitorEmailRecipientSubscription(BaseModel):
+ """Per-recipient opt-in state for monitor email notifications.
+
+ External recipients (not members of the team that owns the monitor) must
+ confirm their subscription via a one-time email before they receive any
+ monitor notifications. Team members are auto-confirmed.
+
+ Statuses:
+ - ``pending`` - confirmation email sent, no notifications yet
+ - ``confirmed`` - notifications enabled
+ - ``unsubscribed`` - recipient opted out and cannot be re-added without
+ a new confirmation flow
+ """
+
+ model_config = {"populate_by_name": True}
+
+ email: str
+ status: Literal["pending", "confirmed", "unsubscribed"]
+ source: Literal["team", "opt_in", "legacy"]
+ confirmation_email_sent: Optional[bool] = Field(
+ default=None, alias="confirmationEmailSent"
+ )
+
+
class MonitorTarget(BaseModel):
"""A scrape or crawl target stored on a monitor."""
@@ -938,6 +962,12 @@ class Monitor(BaseModel):
targets: List[Dict[str, Any]]
webhook: Optional[Dict[str, Any]] = None
notification: Optional[Dict[str, Any]] = None
+ # Present on create/update/get when the API has reconciled email
+ # recipients (i.e. notification.email.recipients is non-empty). Each
+ # entry reports a recipient's opt-in status.
+ email_recipient_subscriptions: Optional[List[MonitorEmailRecipientSubscription]] = (
+ Field(default=None, alias="emailRecipientSubscriptions")
+ )
retention_days: int = Field(alias="retentionDays")
estimated_credits_per_month: Optional[int] = Field(default=None, alias="estimatedCreditsPerMonth")
last_check_summary: Optional[MonitorSummary] = Field(default=None, alias="lastCheckSummary")