Skip to content
supastack
Browse documentation
WebNext.js

For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /docs/web/email.md (or send Accept: text/markdown).

Email and mailing

Transactional templates, preview tooling, and provider adapters.

Ask about this guide
Open in

Read your first local message, then enable delivery

Transactional email means a message triggered by an app action, such as a sign-in code or task result. With the Web server running, keep EMAIL_PROVIDER=local in apps/web/.env.local. Complete database setup, request a sign-in code at /auth, then open /mail-preview and inspect the latest message. A local message appearing here is not an email delivered to your external inbox.

To send real messages, choose one email provider, create its account, verify a domain you control and follow its dedicated guide. Put the named API key and sender address in apps/web/.env.local, save and restart the Web server. Request one new sign-in code, then check both the provider's delivery log and the destination inbox, including spam. Domain verification and sender approval can take time.

If the message fails, inspect the delivery error and sender verification before requesting repeatedly. The /mail-preview route is development-only and returns 404 in production. Keep marketing outreach separate from this transactional sender so a newsletter campaign cannot disrupt account verification mail.

Keep transactional delivery separate

The email module handles transactional product messages, including authentication and task completion. Outreach belongs to the consuming product’s own workflow and must remain separate from this transactional path.

Configure the delivery adapter

Use the local adapter for deterministic tests. Configure the selected production adapter and its server-side credentials before enabling external delivery. Never place mail-provider secrets in client configuration or logs.

Record delivery independently

A generated result and its completion email have separate outcomes. Inspect delivery records before claiming a message was sent successfully. Test a failed delivery without treating it as a failed generation or submitting duplicate model work.

Setup and configuration

EMAIL_PROVIDER=local keeps delivery deterministic during development. For production delivery pick one of the configured adapters — Resend (RESEND_API_KEY), AWS SES (AWS_REGION plus access keys), Postmark, SendGrid, Mailgun, generic SMTP, or Brevo — and verify EMAIL_FROM matches a sender identity the provider accepts.

All templates live in src/transactional-mail-templates.ts. The dev-only /mail-preview route renders every template so changes are reviewed visually instead of by sending mail.

EMAIL_PROVIDER=resend
EMAIL_FROM=Your Product <[email protected]>

Implementation workflow

Authentication codes, magic links, invitations, billing notices, and task-completion mail all pass through the same transactional sender with the resolved locale's copy. Outreach campaigns are a separate product concern and never share this path.

Preview a template in mail-preview before editing copy or layout; keep brand values (name, colors, logo tiles) coming from configuration so derived products restyle without forking templates.

Verification and troubleshooting

Assert on the local adapter's recorded messages in tests — recipient, subject, and rendered body. A failed send must surface as a delivery outcome, not a crashed workflow. Use the opted-in smoke path with REAL_SMOKE_EMAIL_ALLOWED_DOMAIN for real delivery.

Frequently asked questions

14 questions

What is supastack?

supastack is a modular foundation for building AI-powered SaaS products. It brings together common infrastructure so you can focus on product-specific features.

Does it support web and mobile?

Yes. supastack includes Next.js and Expo apps as starting points for web and mobile experiences.

What authentication is included?

Better Auth covers email OTP, magic-link, and social sign-in; email/password stays available at the API layer and through the Auth.js credentials engine for products that need it. Personal workspaces are provisioned with the account so product records stay scoped from day one.

How does it support AI?

supastack includes configurable multi-provider AI, usage tracking, budgets, and encrypted bring-your-own-key support.

How are subscriptions handled?

For products built on the kit, Stripe billing, subscriptions, and entitlements form the paid-access foundation. Provider secrets stay server-only.

Where does my product-specific code live?

Product-specific features remain in a separate codebase while the product configures and integrates supastack’s foundation modules.

How does supastack pricing work?

The kit is a one-time purchase with lifetime updates: One Platform at $249 (temporary launch price, $100 off the regular $349) — your pick of Next.js (Web), Expo (iOS & Android), or Tauri (macOS & Windows Desktop) — or the All Platforms Bundle at $499 (temporary launch price, $100 off the regular $599) with every platform and the full monorepo, plus $75 per extra developer seat. No kit subscription. Checkout on this site delivers your license key by email, with repository access via GitHub invite.

How do workspaces scope my data?

User-owned records are scoped by workspaceId. Identity, entitlements, AI usage, billing events, and audit entries stay inside the personal workspace boundary.

How do background jobs work?

Trigger.dev is the explicit job runtime. The JobRunner contract only promises enqueue, status, and cancel—workflow semantics stay Trigger.dev-specific and explicit.

How is email different from outreach?

Transactional email covers product workflows such as completion notices. Cold outreach and campaigns are product concerns outside this kit’s email module.

How do mobile purchases work?

Mobile includes native purchases and restore through RevenueCat, with access verified by your server. Configure the store accounts and complete device testing before release. Web billing remains separate.

Where do AI provider keys live?

Bring-your-own-key credentials are encrypted and stay server-only. Keys are redacted from logs; usage and budgets remain visible at the workspace level.

Which payment methods does checkout accept?

The Stripe-hosted checkout accepts cards and can also offer Alipay and WeChat Pay once those wallets are enabled on the Stripe account — handy for buyers in China. Wallet authorizations confirm asynchronously, so the license page updates as soon as the payment clears.

Can I get a refund?

After you've got access to the repository, supastack is yours forever, so it cannot be refunded. But rest assured, you get the complete source code with lifetime updates to build and ship unlimited products for yourself or clients. You just cannot resell the code or redistribute the repository as a starter kit or template.

EN
Theme