Transactional emails that look right and land

Paste into any coding agent: Claude Code, Cursor, Codex, Copilot, Windsurf or Cline.

# Transactional emails that look right and land

The welcome, verification, receipt and reset emails are often the first thing a new user of the production site sees after signing up. Review every email the app sends and make them consistent, readable in Gmail, Outlook and Apple Mail (light and dark), and safe from common template bugs.

Site: not given. Find the production URL in the project config, or ask me.

## Ground rules

1. Read before you write. Explore the parts of the codebase this job touches and tell me what is already in place.
2. Plan, then stop. Give me a numbered plan: what you will change, in which files, and why. Wait for my approval before editing anything.
3. Fix things at their source (the shared layout, the config, the generator), not with one-off patches page by page.
4. Keep the project's conventions: its framework APIs, file layout, naming and code style. Add no new dependency without asking.
5. Where something is already done well, say so and leave it alone.

## You will not

- Edit `.env` files, secrets or API keys, or print their values.
- Deploy, push, merge or publish anything.
- Delete data, or run migrations or scripts against a production database.
- Add tracking, third-party scripts or links to any site I did not ask for.
- Change copy, design or behaviour that this job does not need.
- Send emails to real users.
- Change what triggers an email without asking.

## Your stack

- Framework: Work out the framework, router and build output from the project files (package.json, lockfiles, framework config) before planning, and say which you found.
- Host: Work out where the site is hosted from the config files (vercel.json, netlify.toml, wrangler config, Dockerfile, fly.toml) and say which you found.

## Steps

### 1. Inventory

List every email the app sends, what triggers it, the template file and the sending code. Note duplicates, emails with no plain-text part, and emails built by string concatenation.

### 2. One template system

Move emails to one shared layout (the project's email library if it has one, such as React Email, MJML or the framework's mailer views): header, body, one clear button, footer with the company name and address where the law asks for it. Escape every value that comes from users (names, product names) so it cannot inject markup.

### 3. Readable everywhere

Use table-based or library-generated HTML that survives Outlook, inline styles, a max width near 600px, readable font sizes, and colors that work in dark mode (avoid pure black text on transparent backgrounds and logos that disappear on dark). Always include a plain-text part.

### 4. Senders and links

From addresses on the site's domain with a recognizable name, a Reply-To that reaches a person, absolute HTTPS links, and subject lines that say what the email is. Add a way to preview each template locally with sample data.

## Done means

- [ ] Every email the app sends is listed with its trigger and template.
- [ ] All emails share one layout, escape user values and include a plain-text part.
- [ ] Templates render well in light and dark mode at mobile width.
- [ ] From and Reply-To addresses are on the domain, and every template can be previewed locally.

## Report back

When you finish, give me:

- what you changed, file by file;
- anything you skipped, and why;
- anything I must do by hand (DNS records, dashboards, accounts, deploys);
- how to check each change on the live site.