Email

The email subsystem in packages/email separates rendering (React Email components, provider-agnostic) from delivery (a sendEmail function that branches on EMAIL_DELIVERY_MODE). Templates are React components; delivery is currently wired to Plunk but the seam to swap providers is one function. The default mode in dev writes every send to .local/email-outbox/ as an HTML file, so local development never requires a real provider account.

How An Email Flows

Why log mode is the default. A fresh clone runs pnpm dev, signs up, and immediately gets a verification email rendered to a real HTML file you can open in any browser. You see exactly what your users would see, without signing up for anything. You can keep developing for weeks without a Plunk account.

Why three modes. log for dev, noop for tests and CI (silent, fast, no I/O), plunk for production. The mode is resolved at module load by resolveEmailDeliveryMode and is fixed for the process lifetime.

The diagram source lives at apps/docs/diagrams/email-flow.mmd. Rerun pnpm --filter @syntaxkit/docs diagrams:build after editing it to refresh both SVG variants.

Package Layout

The package exposes two subpaths so consumers can pick what they need: import { sendEmail, renderEmail } from "@syntaxkit/email" for the transport layer, and import { WelcomeEmail } from "@syntaxkit/email/templates" for the React components themselves.

Three Delivery Modes

The mode resolution order is: explicit EMAIL_DELIVERY_MODE wins, else PLUNK_API_KEY set means plunk, else NODE_ENV=test means noop, else log. So you only need to set EMAIL_DELIVERY_MODE explicitly when you want to override the smart default. A common case: forcing noop in a non-test environment to silence email entirely.

What Ships Out Of The Box

Twelve templates are wired to live senders. The five auth-driven templates plus the shared EmailLayout chrome are localized via @syntaxkit/i18n; the remaining seven (billing + contact) are still English-only and follow the same pattern when you're ready to localize them. Every template uses the shared EmailLayout so the brand chrome stays consistent.

The bundle covers three areas: authentication (verification, password reset, email change, organization invitation, welcome), billing (subscription created, subscription canceled, trial ending, payment succeeded, payment failed, payment action required), and other (the public contact form).

Templates are React components, which makes them easy to read and extend. The smallest live one, WelcomeEmail, is a fair representation of the shape:

import { Button, Text } from "@react-email/components";
import { defaultLocale, type Locale } from "@syntaxkit/i18n";
import { EmailLayout } from "./components/email-layout";
import { heading, paragraph, button } from "./components/email-styles";
import { getEmailTranslatorWithBrand } from "../src/i18n";

interface WelcomeEmailProps {
  userName?: string;
  loginUrl?: string;
  locale?: Locale;
}

export function WelcomeEmail({
  userName,
  loginUrl = "/",
  locale = defaultLocale,
}: WelcomeEmailProps) {
  const t = getEmailTranslatorWithBrand(locale, "Welcome");
  return (
    <EmailLayout preview={t("preview")} locale={locale}>
      <Text style={heading}>{t("heading")}</Text>
      <Text style={paragraph}>
        {userName
          ? t("greetingNamed", { name: userName })
          : t("greetingAnonymous")}
      </Text>
      <Button style={button} href={loginUrl}>
        {t("ctaButton")}
      </Button>
    </EmailLayout>
  );
}

Localization

The five auth-driven templates and the shared EmailLayout are translated via next-intl using a per-package message catalog at packages/email/messages/<locale>.json. Adding a locale is a JSON file plus an entry in messagesByLocale in packages/email/src/i18n.ts, with no global wiring elsewhere.

Why a per-package catalog. @syntaxkit/email is consumed by @syntaxkit/auth, @syntaxkit/payments, and the contact-form oRPC procedure. Sharing apps/web/messages/<locale>.json would couple the email package back to a specific app and break the dependency direction. The email catalog is independent.

Why createTranslator and not getTranslations. Several email send sites run outside an active next-intl request scope: the welcome email fires from a Better Auth database hook, and Stripe webhook handlers don't carry one either. createTranslator({ locale, messages, namespace }) works synchronously with explicit messages, so it's safe everywhere.

Locale resolution chain. Every auth send site uses resolveAuthEmailLocale (packages/auth/src/locale.ts, re-exported from @syntaxkit/auth). It accepts either a full Request (BA-side hooks) or a bare Headers instance (oRPC handlers, via context.headers), so both code paths read the same NEXT_LOCALE cookie identically:

1. NEXT_LOCALE cookie on the in-flight request: the user's current preference at the moment they triggered the action.
2. User.locale column: their persisted preference; survives across browsers and into flows that have no request (welcome email, future webhook-driven mail).
3. defaultLocale (en): the kit's safety net.

Persisting locale. The setLocale server action in apps/web/i18n/actions.ts writes both the cookie and (when there's a session) the User.locale column, so a logged-in user who switches language gets that preference picked up by subsequent emails. New signups capture the cookie value in the afterUserCreate BA hook so the welcome email and every later send hit the right locale. The User.locale column is nullable; a null value means "no explicit preference, fall back to the cookie or the default".

Invitations. Invitation recipients don't have an account yet, so there's no recipient locale. The send site reads the inviter's User.locale instead and uses it for both the email body and the locale-prefixed getAcceptInvitationPath(locale, id) accept URL. A German team inviting a teammate is overwhelmingly likely to be inviting another German speaker.

The seven non-auth templates (billing, contact) still use hard-coded English. The mechanism is identical when you're ready: add namespaces + strings to both message files, swap the template's hardcoded copy for t(...) calls, and resolve the recipient's locale at the send site (the Stripe webhook handler can read the org owner's User.locale).

Local Development Workflow

Two distinct things to know about.

Preview server. Run pnpm email:dev to launch React Email's preview UI on its own port. Each template renders in isolation with the props you supply, hot-reloads on edit, and you don't have to trigger anything from the app to iterate on copy or styling.

Outbox. When the app actually sends an email in dev (because EMAIL_DELIVERY_MODE=log is the default), the file lands in .local/email-outbox/. Open it in any browser. The first three lines of the HTML are HTML comments with the recipient and subject, so a quick head is enough to scan what was sent without opening every file.

pnpm setup:doctor reports the active mode under "Email" and tells you how to upgrade from log to Plunk when you're ready.

Why The UI Flows Go Through oRPC Instead Of BA Hooks

Better Auth fires its email hooks in the background and catches every throw, so a provider outage or bad PLUNK_API_KEY returns a 200 OK with no email sent. The user hits "check your inbox" and is silently locked out. To surface those failures, the verification, password-reset, email-change, and invitation flows run through oRPC mutations that call sendEmail synchronously and propagate a typed SERVICE_UNAVAILABLE the UI can actually show. The BA hooks stay as best-effort fallbacks for direct API callers.

The deep detail lives in the collapsibles below. Expand only the part you need.

Abuse Protection

Every email-sending surface (verification, password reset, email change, invitation, and the public contact form) runs through the same Upstash-backed abuse policy and the same resolveAbuseDecision helper in packages/shared/src/abuse.ts. The enforcement points live next to the synchronous sendEmail call site in each oRPC mutation (enforceAuthRpcAbusePolicy in packages/api/src/lib/auth-abuse.ts), not in the Better Auth hooks. Those are no-ops or best-effort fallbacks now (see Why The UI Flows Go Through oRPC above).

See Security for the full posture matrix.

Adding A New Template

Switching The Delivery Provider

There is no formal provider-plugin API today; swapping providers means editing the three-way branch in sendEmail. That's deliberately small: about ten lines of code if you mirror the existing Plunk pattern.

Where To Go Next