Email

On This Page

How An Email Flows

Every send goes through renderEmail (React → HTML) then sendEmail. The delivery mode decides what happens next: write a local HTML file, no-op, or call Plunk.

Dev defaults to log, so a fresh clone can sign up and open a real HTML verification email in the browser without a Plunk account. noop keeps tests silent. plunk is production. The mode is resolved once at module load by resolveEmailDeliveryMode and stays fixed for the process lifetime.

Package Layout

Two import subpaths:

• Transport: import { sendEmail, renderEmail } from "@syntaxkit/email"
• Templates: import { WelcomeEmail } from "@syntaxkit/email/templates"

Three Delivery Modes

Resolution order: explicit EMAIL_DELIVERY_MODE wins, else PLUNK_API_KEY set means plunk, else NODE_ENV=test means noop, else log. Set EMAIL_DELIVERY_MODE only to override that default (for example, force noop outside tests).

What Ships Out Of The Box

Twelve templates, all wrapped in shared EmailLayout. Five auth templates plus the layout chrome are localized via @syntaxkit/i18n. The seven billing and contact templates are English-only today; they use the same pattern when you localize them.

Templates are React components. The smallest live one, WelcomeEmail, shows 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 shared EmailLayout use next-intl with a per-package catalog at packages/email/messages/<locale>.json. Add a locale with a JSON file plus an entry in messagesByLocale in packages/email/src/i18n.ts. No other global wiring.

The email package is consumed by @syntaxkit/auth, @syntaxkit/payments, and the contact-form oRPC procedure. A per-package catalog keeps those packages from depending on apps/web/messages.

Send sites often run outside an active next-intl request scope (welcome email from a Better Auth hook, Stripe webhooks). Use createTranslator({ locale, messages, namespace }) with explicit messages; it works synchronously everywhere. Do not use getTranslations here.

Every auth send site resolves locale through resolveAuthEmailLocale (packages/auth/src/locale.ts, re-exported from @syntaxkit/auth). Pass a full Request (BA hooks) or Headers (oRPC via context.headers). Both paths read the same NEXT_LOCALE cookie:

1. NEXT_LOCALE cookie on the in-flight request.
2. User.locale column (persisted preference; used when there is no request).
3. defaultLocale (en).

setLocale in apps/web/i18n/actions.ts writes the cookie and, when there is a session, the User.locale column. New signups capture the cookie in the afterUserCreate hook so the welcome email matches. User.locale is nullable: null means fall back to the cookie or the default.

Invitation recipients have no account yet, so the send site uses the inviter's User.locale for the body and the locale-prefixed getAcceptInvitationPath(locale, id) accept URL.

The seven non-auth templates still use hard-coded English. To localize one: add namespaces and strings to both message files, swap hardcoded copy for t(...), and resolve the recipient locale at the send site (Stripe handlers can read the org owner's User.locale).

Local Development Workflow

Preview server. Run pnpm email:dev to open React Email's preview UI. Each template renders in isolation with the props you supply and hot-reloads on edit. You do not need to trigger a send from the app.

Outbox. In dev (EMAIL_DELIVERY_MODE=log by default), each send writes a file under .local/email-outbox/. Open it in any browser. The first three lines are HTML comments with the recipient and subject, so head is enough to scan what was sent.

pnpm setup:doctor reports the active mode under "Email" and how to move from log to Plunk.

Why The UI Flows Go Through oRPC Instead Of BA Hooks

Better Auth runs its email hooks in the background and catches every throw. A provider outage or bad PLUNK_API_KEY can still return 200 OK with no email sent. The user sees "check your inbox" and is locked out.

Verification, password-reset, email-change, and invitation flows therefore go through oRPC mutations that call sendEmail synchronously and throw a typed SERVICE_UNAVAILABLE the UI can show. BA hooks stay as best-effort fallbacks for direct API callers.

Expand the recipe you need.

Abuse Protection

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

See Security for the full posture matrix.

Adding A New Template

Switching The Delivery Provider

There is no provider-plugin API today. Swap providers by editing the three-way branch in sendEmail (about ten lines if you mirror the Plunk pattern).

Where To Go Next

Also useful: API for contact-form and other oRPC senders, Setup for the email env block, Environment Variables for abuse-protection toggles, and Security for the full abuse posture.