Sending emails
Every email is a React component in your emails/ folder. You give it typed props, renderEmail turns it into a subject, HTML and plain text, and any email provider sends those.
Install and render
An email installs to emails/ at your project root, with the parts it shares in emails/_shared/. Put your product’s name, help page and address in emails/_shared/brand.ts once, and every email uses them.
Terminal
1 line
reset-password.ts
11 lines
Send with your provider
Pass the subject, HTML and text to whichever service sends your mail.
send-with-resend.ts
11 lines
send-with-postmark.ts
12 lines
send-with-smtp.ts
11 lines
Dark mode
Inboxes handle dark mode four different ways, and only some of them let an email choose its own colours.
- Apple Mail, Outlook for Mac, Samsung Email
- Use the email's own dark colours, from emails/_shared/theme.ts.
- Outlook.com and the Outlook apps
- Recolour anything under 4.5:1 contrast. Every colour pair in the theme passes, and the same dark colours are mirrored for them.
- Gmail's iOS and Android apps, classic Outlook for Windows
- Invert the light design themselves. It's built to survive that: no pure white, no boxes, and a button with a thin rim that stays visible. Gmail's apps keep it light when colorScheme is "light-only".
- Gmail on the web, Yahoo, AOL
- Show the light design as written, inside their dark interface.
To keep an email light in Gmail’s apps, pass colorScheme: "light-only". Use it only when the design can’t be inverted: people who chose dark mode often want their email dark too.
light-only.ts
1 line
Rules that keep emails working
- Use a button only when nothing happens until the reader clicks: a confirmation, a reset, a sign-in, an invitation, a card to update. Everything else is a link inside a sentence.
- Codes stay out of the subject line unless you pass codeInSubject: a subject shows on a locked phone.
- Send the text part with the HTML. Some people and filters read only that.
- Send the HTML as renderEmail returns it. Formatting or minifying it again can break the comments Outlook reads.
- Images need absolute https URLs and a width and height. Gmail shows no base64 images, and Outlook ignores CSS sizes on images.
- Keep each email under about 100 KB of HTML. Gmail clips anything larger, hiding the end of it.
- Style with the values in theme.ts: hex colours and px sizes. Email clients drop rem, oklch(), CSS variables, flexbox and grid.
- Send password resets whether or not the address has an account, so the email can't be used to find out who has one.
- Offer a code as well as a link for sign-in and verification. Security scanners in work inboxes open links first, which can use up a one-time link.
Before you ship
- Preview every variant here in light, dark and forced dark, and as plain text.
- Run Mailpit or React Email's preview server locally to catch real sends.
- Before launch, send each email to Gmail on iOS and Android, Apple Mail, Outlook.com, Outlook for Windows and Yahoo, with dark mode on and off.