Email

Local capture and production delivery

packages/mail/src/index.ts owns the mail interface, HTML escaping, and environment checks. Authentication uses it for verification, codes, and password recovery.

Development captures messages for the /dev/mail inbox instead of sending to real recipients. Production requires an EMAIL binding and a verified sender domain for Cloudflare Email Sending. Settings copied from a Next.js starter's other mail provider are not automatically recognized.

Verify local mail

1. Run pnpm muse:init and pnpm dev.
2. Trigger registration or password recovery.
3. Open /dev/mail in the same development instance and find the recipient and subject.
4. Follow the captured link and complete verification or recovery, then sign in.

Seed users are useful for a quick preview. Use a separate development account to exercise actual registration. Keep codes and reset links out of public issue screenshots.

Configure production sending

Enable Email Sending in your own Cloudflare account and verify the sender domain and DNS as required by the dashboard. Check the current Cloudflare Email Service documentation for eligibility and setup requirements.

Set root .env or encrypted CI variables:

MAIL_FROM=Your Product <[email protected]>
APP_URL=https://app.your-domain.com

The deployment must include an EMAIL binding. MAIL_FROM alone does not create sending capability. Production checks reject a missing binding or an @example.com placeholder. Domain verification also does not prove inbox delivery; perform a real delivery check.

Customize messages

Trace the authentication trigger into the mail package before editing subjects, HTML, and action links. Escape user-controlled text before inserting it into HTML. Preserve code, expiry, and action semantics. When rebranding, review the sender name, subject, support address, and APP_URL together.

Do not cache authentication links in public pages. Logs should contain actionable event/result information without complete tokens, message bodies, or credentials.

Production acceptance

• Register and verify an account on your own production origin; check the link's domain.
• Complete password recovery and verify expired links fail.
• Inspect spam folders, sender DNS, and sending-service errors.
• Production /dev/mail and its API must not expose captured authentication mail.
• Failed requests need visible retryable errors, not a success state based only on submission.

The public demo at https://flare.musemvp.com is useful for UI inspection. HTTP smoke results are not evidence of real mail delivery.

Troubleshoot

For missing local messages, check development mode, whether the operation generated mail, and the instance/port. For production rejection, inspect EMAIL, MAIL_FROM, domain verification, and account capability. For links pointing to the wrong site, inspect APP_URL and process-variable precedence. Never expose the development inbox to solve delivery problems.

Continue with authentication and deployment.