Skip to content

Open source CapCut alternative.

TypeScript

feat(site): forecast the daily email quota

David Le1bbc1fdcb514
diff --git a/docs/guides/config-and-experiments.md b/docs/guides/config-and-experiments.md
index aa672fc3..fa300f51 100644
--- a/docs/guides/config-and-experiments.md
+++ b/docs/guides/config-and-experiments.md
@@ -131,6 +131,7 @@ by variant as well.
## Promotions
A promotion is one email from su to an audience, minus anyone an earlier promotion reached; the Pro offers behind it (subscribe bonus, allowance multiplier) are Product-tab settings.
+Every outbound email is a row in one outbox, sent by one drainer in priority order under a daily cap shared by the whole site. A promotion queues its most recently active recipients first and stops at what the rest of the day is forecast to need for welcome and credit emails, and for mail sent by hand during work hours, then picks up the slots that go unused as the day runs down. The cap, the reserves and the work hours are the Daily email sends setting, and the order between kinds is the Email priorities setting.
A credit promotion is a credit offer: one row that promises an account an
amount, the credit's life, and the window it can be claimed in, then records
diff --git a/site/prisma/Email.prisma b/site/prisma/Email.prisma
index 3a15be35..f43bbff3 100644
--- a/site/prisma/Email.prisma
+++ b/site/prisma/Email.prisma
@@ -14,3 +14,45 @@ model UserEmailSettings {
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
}
+
+// The outbox. Every email the site sends is a row here first; one drainer
+// sends rows in priority order under the day's quota
+// (src/lib/email/outbox.ts). The row is the send's record: a retried queue
+// call adds nothing because the idempotency key is unique.
+model EmailSend {
+ id String @id @default(cuid())
+ // One of EMAIL_KIND_IDS (src/lib/email/kindIds.ts).
+ kind String
+ // Higher goes first: the kind's priority when the row was queued.
+ priority Int
+ // Order within a priority. A promotion's most recently active recipient is 0.
+ rank Int @default(0)
+ userId String?
+ user User? @relation(fields: [userId], references: [id], onDelete: Cascade)
+ promotionId String?
+ promotion Promotion? @relation(fields: [promotionId], references: [id], onDelete: Cascade)
+ // What the kind's builder needs to make the message.
+ payload Json
+ idempotencyKey String @unique
+ // "queued" | "sending" | "sent" | "failed" | "skipped"
+ state String @default("queued")
+ attempts Int @default(0)
+ error String?
+ // A failed attempt pushes the next one out.
+ notBefore DateTime @default(now())
+ sentAt DateTime?
+ createdAt DateTime @default(now())
+ updatedAt DateTime @updatedAt
+
+ @@index([state, priority, rank, createdAt])
+ @@index([promotionId, state])
+}
+
+// Global outbound email cap for free-tier limits: how many emails were sent
+// on each UTC calendar day.
+model EmailDailyQuota {
+ day String @id
+ sent Int @default(0)
+ createdAt DateTime @default(now())
+ updatedAt DateTime @updatedAt
+}
diff --git a/site/src/lib/config/registry.ts b/site/src/lib/config/registry.ts
index dc5d9137..183d6159 100644
--- a/site/src/lib/config/registry.ts
+++ b/site/src/lib/config/registry.ts
@@ -9,6 +9,8 @@ import {
type SettingsOf,
} from "@donkeycut/abexp";
import { z } from "zod";
+import { promotionOfferSchema } from "@/lib/marketing/promotionOfferInput";
+import { DEFAULT_EMAIL_PRIORITIES, EMAIL_KIND_IDS } from "@/lib/email/kindIds";
import { maxCreditGrantDollars, maxCreditGrantExpiryDays } from "@/lib/credits/top-up";
@@ -19,7 +21,23 @@ import { maxCreditGrantDollars, maxCreditGrantExpiryDays } from "@/lib/credits/t
// declarations the server validates against. A feature that people might
// tune ships its setting here in the same change.
+function validTimeZone(zone: string): boolean {
+ try {
+ new Intl.DateTimeFormat("en-US", { timeZone: zone });
+ return true;
+ } catch {
+ return false;
+ }
+}
+
export const SETTINGS = defineSettings({
+ promotionCreditOffer: {
+ schema: promotionOfferSchema.extend({ minimumAccountAgeDays: z.number().int().min(1).max(36500) }).strict(),
+ default: { dollars: 15, claimWindowDays: 3, expiresAfterDays: 28, minimumAccountAgeDays: 7 },
+ public: false,
+ title: "Promotion credit offer",
+ description: "Default credit offer and minimum account age for new promotion drafts. Saved drafts keep their terms.",
+ },
chatRuntime: {
schema: z.object({
syncIntervalMs: z.number().int().min(1000).max(30000),
@@ -78,6 +96,54 @@ export const SETTINGS = defineSettings({
title: "Signup credits",
description: "USD a new account is granted at signup, and how many days the grant lives.",
},
+ emailDailySend: {
+ schema: z
+ .object({
+ // Emails the provider lets the account send per UTC day.
+ providerLimit: z.number().int().min(1).max(100000),
+ // Slots kept free for emails sent by hand while work hours remain in
+ // the UTC day; released once the work day is over.
+ manualReserve: z.number().int().min(0).max(100000),
+ manualTimeZone: z.string().refine(validTimeZone, "Unknown IANA time zone"),
+ // Work hours in that zone, start inclusive and end exclusive.
+ manualStartHour: z.number().int().min(0).max(23),
+ manualEndHour: z.number().int().min(1).max(24),
+ manualWeekdaysOnly: z.boolean(),
+ // Days of signup history the transactional forecast averages over.
+ signupLookbackDays: z.number().int().min(1).max(90),
+ // Slots kept free beyond the forecast for transactional email the
+ // forecast cannot see, such as credit offers sent by hand.
+ transactionalHeadroom: z.number().int().min(0).max(100000),
+ })
+ .strict()
+ .refine((v) => v.manualStartHour < v.manualEndHour, { message: "Work hours must end after they start." })
+ .refine((v) => v.manualReserve + v.transactionalHeadroom < v.providerLimit, {
+ message: "The reserves must leave room for bulk sends.",
+ }),
+ default: {
+ providerLimit: 99,
+ manualReserve: 10,
+ manualTimeZone: "Asia/Seoul",
+ manualStartHour: 9,
+ manualEndHour: 18,
+ manualWeekdaysOnly: true,
+ signupLookbackDays: 7,
+ transactionalHeadroom: 5,
+ },
+ public: false,
+ title: "Daily email sends",
+ description:
+ "The provider's daily send cap, the slots held for emails sent by hand during work hours, and how the transactional forecast that holds slots ahead of promotions is sized.",
+ },
+ emailPriorities: {
+ schema: z
+ .object(Object.fromEntries(EMAIL_KIND_IDS.map((id) => [id, z.number().int().min(0).max(1000)])))
+ .strict(),
+ default: { ...DEFAULT_EMAIL_PRIORITIES },
+ public: false,
+ title: "Email priorities",
+ description: "The order the outbox sends in when the day's quota is short: higher goes first. A change applies to emails queued from then on.",
+ },
creditExpiryNotice: {
schema: z
.object({
@@ -144,7 +210,7 @@ export const SETTINGS = defineSettings({
// The settings su shows on its Product tab: what an account gets. The
// settings tab under Experiments still lists every key.
-export const PRODUCT_SETTING_KEYS = ["signupCredits", "creditExpiryNotice", "manualCreditOffer", "subscribeBonus", "proAllowancePromotion"] as const satisfies readonly SettingKey[];
+export const PRODUCT_SETTING_KEYS = ["signupCredits", "creditExpiryNotice", "manualCreditOffer", "promotionCreditOffer", "subscribeBonus", "proAllowancePromotion"] as const satisfies readonly SettingKey[];
export type SettingKey = keyof typeof SETTINGS;
export type Settings = SettingsOf<typeof SETTINGS>;
diff --git a/site/src/lib/email/credit-expiry-due.ts b/site/src/lib/email/credit-expiry-due.ts
new file mode 100644
index 00000000..660177dc
--- /dev/null
+++ b/site/src/lib/email/credit-expiry-due.ts
@@ -0,0 +1,42 @@
+import type { Prisma } from "@/generated/prisma/client";
+import { zeroCreditMicros } from "@/lib/credits/amounts";
+import { prisma } from "@/lib/prisma";
+
+// The grants an account is warned about: credit it was given. Purchased
+// credit never expires, and the Pro allowance turns over every month.
+export const NOTICED_GRANT_SOURCES = ["signup", "manual_dollar", "subscribe_bonus"] as const;
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+export function metadataObject(metadata: Prisma.JsonValue | null): Prisma.JsonObject {
+ return metadata !== null && typeof metadata === "object" && !Array.isArray(metadata)
+ ? metadata
+ : {};
+}
+
+/** Whether the grant's account has already been told this grant expires. */
+export function expiryNoticed(metadata: Prisma.JsonValue | null): boolean {
+ return typeof metadataObject(metadata).expiryNoticeSentAt === "string";
+}
+
+/** Grants still owed an expiry notice: expiring inside the window, holding
+ * credit, and never noticed. */
+export async function pendingCreditExpiryGrants(now: Date, withinDays: number) {
+ const grants = await prisma.userCreditGrant.findMany({
+ orderBy: { expiresAt: "asc" },
+ select: {
+ id: true,
+ expiresAt: true,
+ metadata: true,
+ remainingAmountMicros: true,
+ user: { select: { email: true, id: true, name: true } },
+ },
+ where: {
+ expiresAt: { gt: now, lte: new Date(now.getTime() + withinDays * DAY_MS) },
+ remainingAmountMicros: { gt: zeroCreditMicros },
+ source: { in: [...NOTICED_GRANT_SOURCES] },
+ status: "active",
+ },
+ });
+ return { due: grants.length, pending: grants.filter((g) => !expiryNoticed(g.metadata)) };
+}
diff --git a/site/src/lib/email/daily-send-limit.ts b/site/src/lib/email/daily-send-limit.ts
new file mode 100644
index 00000000..4cba6ef0
--- /dev/null
+++ b/site/src/lib/email/daily-send-limit.ts
@@ -0,0 +1,128 @@
+import { utcDayOf } from "@/lib/analytics/schema";
+import { getGlobalSetting } from "@/lib/config/effective";
+import { expectedTransactionalSends, manualHoursRemainToday, type TransactionalForecast } from "@/lib/email/send-forecast";
+import { prisma } from "@/lib/prisma";
+
+// One counter per UTC day, three ceilings on it. Manual sends run up to the
+// provider's cap. Transactional sends stop below the slots held for hand-sent
+// mail while work hours remain. Bulk sends stop below what the rest of the
+// day is forecast to need for transactional email, so a promotion never
+// blocks a welcome email and takes the slots the forecast releases as the
+// day runs down. A slot is counted when it is reserved and given back when
+// the send fails, so a process that dies mid-send costs the day one slot.
+export type EmailSendKind = "manual" | "transactional" | "bulk";
+
+// How long a refused send waits before asking again while the day's
+// ceilings still hold slots back; they rise as the day goes on.
+const FORECAST_RETRY_SECONDS = 15 * 60;
+
+export class DailyEmailSendLimitError extends Error {
+ public constructor(
+ public readonly day: string,
+ public readonly kind: EmailSendKind,
+ public readonly limit: number,
+ public readonly remaining: number,
+ public readonly retryAfterSeconds: number,
+ ) {
+ super(`Daily email limit reached for ${kind} sends on ${day}: ${remaining} of ${limit} available.`);
+ this.name = "DailyEmailSendLimitError";
+ }
+}
+
+function secondsUntilNextUtcDay(now: Date): number {
+ const next = new Date(now);
+ next.setUTCHours(24, 0, 0, 0);
+ return Math.max(1, Math.ceil((next.getTime() - now.getTime()) / 1000));
+}
+
+export type DailyEmailQuotaStatus = {
+ day: string;
+ sent: number;
+ providerLimit: number;
+ // Slots held for hand-sent mail right now; 0 once the work day is over.
+ manualReserve: number;
+ forecast: TransactionalForecast;
+ ceilings: Record<EmailSendKind, number>;
+ resetsInSeconds: number;
+};
+
+/** Where the day stands: what went, and how far each kind of send can go. */
+export async function dailyEmailQuotaStatus(now = new Date()): Promise<DailyEmailQuotaStatus> {
+ const day = utcDayOf(now);
+ const [setting, row] = await Promise.all([
+ getGlobalSetting("emailDailySend"),
+ prisma.emailDailyQuota.findUnique({ select: { sent: true }, where: { day } }),
+ ]);
+ const manualReserve = manualHoursRemainToday(now, setting) ? setting.manualReserve : 0;
+ const forecast = await expectedTransactionalSends(now, setting);
+ const transactional = setting.providerLimit - manualReserve;
+ return {
+ day,
+ sent: row?.sent ?? 0,
+ providerLimit: setting.providerLimit,
+ manualReserve,
+ forecast,
+ ceilings: { manual: setting.providerLimit, transactional, bulk: transactional - forecast.total },
+ resetsInSeconds: secondsUntilNextUtcDay(now),
+ };
+}
+
+async function ceilingFor(kind: EmailSendKind, now: Date): Promise<{ limit: number; floor: number }> {
+ const { ceilings, forecast, providerLimit } = await dailyEmailQuotaStatus(now);
+ // The lowest any ceiling can settle at tonight: the cap minus the headroom
+ // the forecast keeps to the end.
+ const floor = kind === "bulk" ? providerLimit - forecast.headroom : providerLimit;
+ return { limit: ceilings[kind], floor };
+}
+
+async function reserveSlot(day: string, kind: EmailSendKind, now: Date): Promise<void> {
+ const { limit, floor } = await ceilingFor(kind, now);
+ await prisma.emailDailyQuota.createMany({ data: [{ day }], skipDuplicates: true });
+ // One conditional increment: the row moves only while it is under the
+ // ceiling, so two senders can never both take the last slot.
+ const taken = await prisma.emailDailyQuota.updateMany({
+ data: { sent: { increment: 1 } },
+ where: { day, sent: { lt: limit } },
+ });
+ if (taken.count > 0) return;
+
+ const row = await prisma.emailDailyQuota.findUnique({ select: { sent: true }, where: { day } });
+ const sent = row?.sent ?? 0;
+ const retryAfterSeconds = sent < floor ? FORECAST_RETRY_SECONDS : secondsUntilNextUtcDay(now);
+ throw new DailyEmailSendLimitError(day, kind, limit, Math.max(0, limit - sent), retryAfterSeconds);
+}
+
+async function releaseSlot(day: string): Promise<void> {
+ await prisma.emailDailyQuota.updateMany({
+ data: { sent: { decrement: 1 } },
+ where: { day, sent: { gt: 0 } },
+ });
+}
+
+/** Runs one provider send inside the day's quota. The slot is kept only when
+ * the provider accepted the email: a thrown error or a resolved `{ error }`
+ * gives it back. */
+export async function withDailyEmailQuota<T extends { error: unknown }>(
+ kind: EmailSendKind,
+ send: () => Promise<T>,
+): Promise<T> {
+ const now = new Date();
+ const day = utcDayOf(now);
+ await reserveSlot(day, kind, now);
+ const release = () =>
+ releaseSlot(day).catch((releaseError) => {
+ console.error("[email] failed to release a daily email slot", {
+ day,
+ error: releaseError instanceof Error ? releaseError.message : String(releaseError),
+ });
+ });
+ let result: T;
+ try {
+ result = await send();
+ } catch (error) {
+ await release();
+ throw error;
+ }
+ if (result.error) await release();
+ return result;
+}
diff --git a/site/src/lib/email/send-forecast.ts b/site/src/lib/email/send-forecast.ts
new file mode 100644
index 00000000..ed7360de
--- /dev/null
+++ b/site/src/lib/email/send-forecast.ts
@@ -0,0 +1,94 @@
+import { getGlobalSetting } from "@/lib/config/effective";
+import { pendingCreditExpiryGrants } from "@/lib/email/credit-expiry-due";
+import { prisma } from "@/lib/prisma";
+import type { Settings } from "@/lib/config/registry";
+
+// What the rest of the UTC day still needs from the provider's send cap, so
+// bulk sends stop where transactional email and hand-sent mail begin and take
+// whatever those leave behind as the day runs down.
+
+export type EmailDailySendSetting = Settings["emailDailySend"];
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const HOUR_MS = 60 * 60 * 1000;
+
+function msOfUtcDay(date: Date): number {
+ return date.getTime() - Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate());
+}
+
+function startOfUtcDay(date: Date): Date {
+ return new Date(date.getTime() - msOfUtcDay(date));
+}
+
+function localHourAndWeekday(date: Date, timeZone: string): { hour: number; weekday: string } {
+ const parts = new Intl.DateTimeFormat("en-US", { hour: "numeric", hour12: false, timeZone, weekday: "short" }).formatToParts(date);
+ const hour = Number(parts.find((p) => p.type === "hour")?.value ?? 0) % 24;
+ const weekday = parts.find((p) => p.type === "weekday")?.value ?? "";
+ return { hour, weekday };
+}
+
+function inManualHours(date: Date, setting: EmailDailySendSetting): boolean {
+ const { hour, weekday } = localHourAndWeekday(date, setting.manualTimeZone);
+ if (setting.manualWeekdaysOnly && (weekday === "Sat" || weekday === "Sun")) return false;
+ return hour >= setting.manualStartHour && hour < setting.manualEndHour;
+}
+
+/** Whether any work hour is still ahead in the current UTC day, sampled at
+ * now and at every top of the hour until UTC midnight. */
+export function manualHoursRemainToday(now: Date, setting: EmailDailySendSetting): boolean {
+ const dayEnd = startOfUtcDay(now).getTime() + DAY_MS;
+ for (let t = now.getTime(); t < dayEnd; t = Math.floor(t / HOUR_MS + 1) * HOUR_MS) {
+ if (inManualHours(new Date(t), setting)) return true;
+ }
+ return false;
+}
+
+/** Welcome emails still expected today: signups over the lookback window that
+ * landed later in their UTC day than now is in this one, averaged per day. */
+async function expectedSignupsRemaining(now: Date, lookbackDays: number): Promise<number> {
+ const today = startOfUtcDay(now);
+ const since = new Date(today.getTime() - lookbackDays * DAY_MS);
+ const users = await prisma.user.findMany({
+ select: { createdAt: true },
+ where: { createdAt: { gte: since, lt: today } },
+ });
+ const cutoff = msOfUtcDay(now);
+ const later = users.filter((u) => msOfUtcDay(u.createdAt) >= cutoff).length;
+ return Math.ceil(later / lookbackDays);
+}
+
+// A campaign asks once per email, every half second; the answer moves by the
+// hour, so one forecast serves a minute of sends.
+const FORECAST_TTL_MS = 60 * 1000;
+let cached: { at: number; value: Promise<TransactionalForecast> } | null = null;
+
+export type TransactionalForecast = {
+ // Welcome emails for the signups still expected today.
+ signups: number;
+ // Expiry notices owed and not yet sent.
+ expiry: number;
+ headroom: number;
+ total: number;
+};
+
+/** Transactional sends the rest of today is expected to need. */
+export function expectedTransactionalSends(now: Date, setting: EmailDailySendSetting): Promise<TransactionalForecast> {
+ if (cached && now.getTime() - cached.at < FORECAST_TTL_MS) return cached.value;
+ const value = forecast(now, setting);
+ cached = { at: now.getTime(), value };
+ value.catch(() => {
+ cached = null;
+ });
+ return value;
+}
+
+async function forecast(now: Date, setting: EmailDailySendSetting): Promise<TransactionalForecast> {
+ const { daysBefore } = await getGlobalSetting("creditExpiryNotice");
+ const [signups, pending] = await Promise.all([
+ expectedSignupsRemaining(now, setting.signupLookbackDays),
+ pendingCreditExpiryGrants(now, daysBefore),
+ ]);
+ const expiry = pending.pending.length;
+ const headroom = setting.transactionalHeadroom;
+ return { signups, expiry, headroom, total: signups + expiry + headroom };
+}