Send your first verification email, configure your sender, and customize email templates.
Email enables registration codes, OTP sign-in, password recovery, and contact messages. Configure a real provider when you want these messages delivered to an inbox.
Before You Start
Have a running local app, a test inbox, and a sending domain you can verify. Use Cloudflare Email Sending; Workers production does not support Resend or console delivery. Locally, MAIL_PROVIDER=console prints mail in the dev server terminal. Provider limits depend on your account.
1. Connect Your Provider
Cloudflare Email Sending
Configure a sending domain and obtain an API token with the required email-sending access for your account. Set these values in apps/web-cloudflare/.env.local and .dev.vars:
MAIL_PROVIDER="cloudflare"
CLOUDFLARE_ACCOUNT_ID="YOUR_ACCOUNT_ID"
CLOUDFLARE_API_TOKEN="YOUR_EMAIL_SENDING_TOKEN"
MAIL_FROM="Acme <[email protected]>"
MAIL_FROM_NEWSLETTER="Acme <[email protected]>"
CONTACT_FORM_TO="[email protected]"
NEXT_PUBLIC_EMAIL_SUPPORT="[email protected]"Set the same server credentials on your production host. Set the same server credentials on your production host before launch.
2. Receive Your First Email
Restart the dev server. Open the login page and request an email sign-in code for an account you control, or use password recovery for an existing account. Check the inbox and spam folder, then finish that flow with the received code.
Check Your Result
- The email arrives with your sender address, product name, and expected language.
- The code completes the intended sign-in or reset flow.
- A contact-form message reaches
CONTACT_FORM_TO. - Newsletter confirmation and signed unsubscribe links work if you use the newsletter feature.
Common Problems
| Problem | Fix |
|---|---|
| No message in the inbox | Check server errors, provider logs, and spam |
| Provider rejects the sender | Verify the sending domain and token permissions; use a sender on that domain |
| Workers works locally but not in production | Check deployed secrets and MAIL_PROVIDER=cloudflare; .dev.vars is not a production secrets store |
| Links point to localhost | Set the deployment's NEXT_PUBLIC_SITE_URL to your HTTPS origin and rebuild |
Customize the Email
Edit shared React Email templates under packages/mail/src/templates/. Current template IDs are emailVerification, magicLink, newsletterSignup, verificationCode, verificationCodeSignin, and verificationCodeForgotPassword.
Preview them with:
pnpm --filter @musemvp/cloudflare exec email dev --dir ../../packages/mail/src/templates --port 4100Open http://localhost:4100. Use this explicit directory: the current root mail:preview script still points at the previous template location.
For a new template, register its ID and add mail.<templateId>.subject in both locales' packages/i18n/src/translations/{en,zh}/mvp.json. Package code uses relative or package imports, not app @/ imports.
From app server code, call:
import { sendEmail } from "@/modules/mail";
await sendEmail({
to: user.email,
locale,
templateId: "verificationCodeSignin",
context: { otp, expiresIn: 300 },
});user, locale, and otp come from your server flow. sendEmail() also supports raw subject / html / text. To add a welcome email, create a template and connect it to your chosen event; it is not an existing default template. Preview checks appearance, not delivery.