How to Get Claude Code to Build HTML Emails That Look Good Everywhere

Your emails look great in the preview. Then one lands in Outlook with the spacing gone, or opens on a phone in dark mode with the logo missing. This guide is for people building SaaS products, sites and tools with Claude Code. It shows how to brief Claude Code so your Claude Code HTML email holds up in the inboxes your users really use.

You'll get the reasons email behaves differently from a web page, the messages to send Claude Code for welcome emails, receipts and password resets, and a short testing routine. You won't need to learn any email code.

Why is HTML email different from a web page?

Emails use HTML, the same language as web pages, but each email client decides how much of it to show. An email client is the program or website someone reads email in, like Gmail, Apple Mail or Outlook. Some show almost everything a browser would. Others ignore large parts of it.

The biggest gap is classic Outlook for Windows. Microsoft says it uses a Word-based engine to process email HTML, with limited support for standard spacing styles. Microsoft is moving people to a new Outlook that works more like a browser, but says existing installs of classic Outlook will be supported until at least 2029. So your emails need to work in it for years yet.

That's why email layouts still use tables, which every client understands, and inline styles, meaning design instructions written onto each element instead of kept in one place. Microsoft recommends both for consistent results. Claude Code knows these methods, so ask for them by name.

What goes in a good Claude Code HTML email brief?

A good Claude Code HTML email brief names the inboxes that matter, asks for email-safe building methods, and describes the look you want. Brief Claude Code the way you'd brief a designer who also builds: what the email is for, who reads it, and where it has to work.

Please build our welcome email as HTML that works in Gmail, Apple Mail and both the classic and new Outlook on Windows. Use a table-based layout with inline styles, one centered column no wider than 600 pixels, and a solid background color rather than a background image. Match the colors and logo on our homepage. Show me a preview when it's ready.

Expect a preview of the email. If something looks off, say so in plain words, such as "the heading feels cramped" or "the button should be our green."

Add three more requests to your brief:

• Real text, not pictures of text. Classic Outlook blocks pictures by default until the reader downloads them, so the button label and key details should be real text.
• Alt text on every image. Alt text is a short description that shows when an image doesn't load, and that screen readers read aloud.
• Valid HTML. Microsoft notes that broken HTML can make some clients, including classic Outlook, show the email as a solid black block. Ask Claude Code to check for errors before you test.

Before we test, check the email's HTML for errors, make sure every image has alt text, and make sure the button and all key information are real text, not images.

If you're designing a whole set of emails, set up one shared look first. See getting Claude Code to design your email templates, using Claude Code as an AI email template generator and briefing Claude Code like a copywriter.

How do you make emails work in dark mode and on mobile?

Choose colors that still read well when the inbox changes them, and use one column with large text and buttons.

Dark mode. Most email clients adjust an email's colors in dark mode, and Microsoft says senders can't fully control this. Apple Mail lets an email set its own dark-mode colors, Outlook does in part, and Gmail and Yahoo Mail don't. So aim for a design that survives any colors the inbox applies:

• A logo on a transparent background with some padding, so it doesn't vanish on dark gray
• Strong contrast between text and background
• No meaning carried by color alone, such as "click the green link"

Mobile. Your users may open these emails on a phone, right after they sign up or buy. Gmail supports screen-width rules, which let an email change its layout on small screens, but not every client does. A single column that already fits a phone is the safest start.

Make the email look right in dark mode and on phones. Use a single column, body text of at least 16 pixels, and buttons big enough to tap with a thumb. Add dark-mode colors where the inbox supports them, and keep the logo visible on a dark background. Show me the dark-mode version too.

Why does every email need a plain-text version?

A plain-text version is a copy of the email with only words and full links, sent inside the same email as the HTML. The email standard lists versions from plainest to richest, and each inbox shows the richest one it can display. So someone using a text-only reader, or an inbox that strips formatting, still gets a readable message. It also matters when the details matter: a password reset link or an order number should be equally clear without the design.

For every email you build, include a plain-text version with the same wording. Write links out in full, keep the information in the same order, and leave out anything that only makes sense with images.

How do you test an HTML email before users see it?

Send real test emails to the inboxes your users use, and check them on a computer and a phone, in light and dark mode. Previews help, but only a real inbox shows what your users will see.

1. Set up test addresses in Gmail, Outlook and Apple Mail, whichever you can reach.
2. Ask Claude Code to send a test of each email. Once an email service such as SimpleSends is connected to Claude Code, it can send test emails from the chat.
3. Open each test on a computer and on a phone. Switch your phone to dark mode and look again.
4. In classic Outlook, look at the email before downloading pictures. Check the message still makes sense.
5. Click every link and button, and check names, dates and amounts are filled in correctly.
6. Tell Claude Code what you found, in plain words, and ask for fixes. Send the tests again.

Send test versions of the welcome, password reset and receipt emails to my test addresses, with sample names and amounts filled in. I'll check them on my laptop and phone and tell you what needs changing.

Our guide to testing emails before your users see them has a full pre-launch checklist, and updating your emails by asking Claude Code covers changes later.

When you're ready to send these emails for real, connect SimpleSends and let Claude Code set up sending for your project.