Email

The email subsystem in packages/email separates rendering (React Email components, provider-agnostic) from delivery. Templates are React components. sendEmail branches on EMAIL_DELIVERY_MODE: log and noop for local work, or one of six providers (Plunk, Resend, Postmark, Brevo, SendGrid, SMTP). The default with no credentials writes every send to .local/email-outbox/ as an HTML file, so local development never requires a 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 a provider. You can keep developing without a Plunk, Resend, or SMTP account.

Why these modes. log for dev, noop for tests and CI (silent, fast, no I/O), and one real provider for production. The mode is resolved at module load by resolveEmailDeliveryMode in packages/shared/src/setup/state.ts 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.

Delivery Modes

The mode resolution order is: explicit EMAIL_DELIVERY_MODE wins. If it is unset, the first configured provider wins, in order: plunk (PLUNK_API_KEY), resend (RESEND_API_KEY), postmark (POSTMARK_SERVER_TOKEN), brevo (BREVO_API_KEY), sendgrid (SENDGRID_API_KEY), smtp (SMTP_HOST, and boot also requires SMTP_USER and SMTP_PASS). If none is set, the mode is noop when NODE_ENV=test, otherwise log. Two or more provider credentials without an explicit mode is a boot error. EMAIL_FROM is required for every real provider.

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. Interactive switches update NEXT_LOCALE client-side, then enqueue the cookie-free persistLocalePreference action in the background. Its per-tab queue keeps one write in flight and collapses rapid changes to the latest locale, so User.locale can't finish out of order within a tab. The cookie-writing setLocale variant remains for server-side callers and defers its database write with after(); interactive flows avoid it because a Server Action cookie mutation re-renders the current route and wipes the client prefetch cache. New signups still 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 log is the default when no provider credential is set), the file lands in .local/email-outbox/. Open it in any browser. The HTML comments store a recipient hash and the subject, not the address.

pnpm setup:doctor reports the active mode under "Email" and tells you how to set EMAIL_DELIVERY_MODE to plunk, resend, postmark, brevo, sendgrid, or smtp when you are 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 a bad credential 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

The kit ships adapters for Plunk, Resend, Postmark, Brevo, SendGrid, and SMTP under packages/email/src/providers/. Set EMAIL_DELIVERY_MODE explicitly when more than one provider's credentials are present; otherwise the auto-resolver picks the first configured provider.

Where To Go Next