Email templates and delivery

Included messages

These are source HTML templates published through the Resend API. The current implementation is not a React Email authoring system and does not require SMTP. scripts/kickstart/templates.mjs defines subjects, variable declarations, aliases and publication verification.

Preview and edit HTML

Open a source HTML file in your editor and preview a copy with synthetic substitution values. Never use a real one-use Auth link in a screenshot. {{APP_NAME}} is replaced and escaped by the installer; Resend's declared runtime variables remain part of the published template contract.

For example, edit the welcome heading to explain your product's first meaningful action. Keep the action URL variable intact and check the result with long product names, narrow email widths and dark-mode email clients. A browser HTML preview checks layout only; it is not equivalent to a received email in several clients.

Subject prefixes are in templateDefinitions in scripts/kickstart/templates.mjs, combined with APP_NAME. Change the relevant subject there rather than editing the live provider template independently. If you add a variable, update its declaration and every sending call together.

Publish and rerun

For an authorized local installation, run:

npm run kickstart:check
npm run kickstart

For an installation with the production origin active, follow its production reconciliation workflow. Do not restore localhost merely to publish an email edit. Restart/redeploy the application when environment IDs or server configuration changes.

Template aliases include project identity and a content fingerprint. Repeating the same content reuses the matching resource after checking it. Changed source content produces a new version identity and saves the appropriate ID. Rerun safety means no duplicate resource for the same project/content attempt; it does not mean every content revision shares one immutable provider ID.

If an owned matching template was edited outside the codebase, the installer stops instead of overwriting it. Reconcile the intended source/provider content first. Existing configured IDs also bind recovery to the same Resend account.

Signed Auth hook

Supabase's hosted Send Email Hook receives Auth email requests, verifies their signature and sends through the configured Resend API templates. Verification, recovery and magic-link values are mapped into narrowly selected function secrets. Google credentials and the Supabase management token are not copied into that hook.

Changing the sender, template IDs, active origin or signing secret requires coordinated configuration. A local .env edit does not by itself update the hosted function. Keep the generated hook secret private and retain the installation receipts.

Application sends and preferences

lib/email/welcome.mjs exposes deliverWelcome(user, env, fetcher) for internal use after successful signup/verification. It requires a confirmed user, checks emailDeliveryDecision before every attempt and uses a stable idempotency key. lib/email/invitation.mjs uses the invitation attempt identity and records accepted, failed, suppressed or unknown outcomes.

To add an application message, start with a trusted server event that already establishes the recipient. Reuse the shared preference lookup before each attempt, add a dedicated template declaration and supply only its declared variables. Create a stable event ID and reuse it across retries. Do not export a generic Server Action that accepts arbitrary to, subject and HTML from a customer.

For a notes notification, the event could say “A note was added” and link to the dashboard. Before including note content, decide how current membership and account inbox retention interact. Email already delivered cannot be recalled after someone leaves a workspace.

Retry and uncertainty

Welcome retries use the same user-bound idempotency identity. Invitations distinguish the saved invitation from an individual send attempt. A timeout may mean the provider accepted the request but its response was lost; that state is unknown, not definitely failed.

An opt-out stops future nonessential attempts. Suppressed invitation rows remain visible for authorized managers, without exposing the recipient's private preference values or whether an account exists. Re-enabling preferences does not automatically send old messages. Verification and password recovery remain essential account-access mail.

Diagnose delivery

Check sender restrictions before changing Auth code. onboarding@resend.dev is limited to the Resend account recipient; verify a production sender for other users. Inspect sanitized provider errors and the active origin, not raw links or tokens.

Verification checklist

Receive each relevant message with synthetic account/workspace names. Inspect subject, sender, body, variables and link destination. Complete verification/recovery/invitation flows, then retry the same provisioning to confirm resource reuse. Test an opted-out account and an uncertain send without claiming guaranteed failure.

No email was sent while authoring this documentation site. Source and layout checks are separate from inbox acceptance. Record real delivery and completed link results on your authorized installation before release.