An HTML email is a message written with the same markup as a web page, so that it can carry colours, images, buttons and a layout. It looks more polished than plain text, but it is also trickier to build, because email apps render HTML far less consistently than browsers do. This guide explains what an HTML email is, why email layouts use old-fashioned techniques, how to build a simple responsive template step by step, how to test and send it, and how HTML and plain text work together.
What is an HTML email?
Every email has a body, and the body can be plain text, HTML or both. In an HTML email, the body contains HTML tags that tell the mail app how to display it: headings, paragraphs, links, images, tables and styling. When the message has both a plain and an HTML version, the standard way to package them is a multipart message, and the mail app picks the one it can show. Our guide to MIME and multipart messages explains the packaging.
Marketing newsletters, receipts and product updates usually use HTML. Personal and many business messages are plain or lightly formatted. Which is better depends on the job; see the comparison below.
Why HTML email is not like web design
A web page runs in a browser that follows modern standards. An email runs in whatever app the reader uses: Gmail on the web, Outlook on Windows, Apple Mail, a phone app, a company's webmail. Each applies its own rules, strips some code and handles styles differently. Some versions of desktop Outlook render messages with an engine based on a word processor, not a browser. This is why email developers keep to older techniques.
- Layouts use tables, not modern grid or flexible-box layout, because tables are rendered consistently.
- Styles are written inline, as a style attribute on each element, since some apps remove or ignore style blocks in the head.
- JavaScript does not run. It is removed for safety.
- Forms and video are unreliable. Link to a web page instead.
- Web fonts are not guaranteed. Pick a font stack that falls back to common system fonts.
- Images are often blocked by default, so the message must make sense without them.
Support changes over time. Before you rely on a feature, look at an up-to-date email client support reference, or test it.
Plain text vs HTML email
| Plain text | HTML | |
|---|---|---|
| Looks | Simple, no images | Branded, images, buttons |
| Effort | Low | Higher; needs testing |
| Reliability | Shown the same everywhere | Varies between apps |
| Best for | Personal notes, support, short alerts | Newsletters, receipts, product updates |
| Tracking | Limited | Links and images can be tracked |
Many senders use both: an HTML version for most readers and a plain-text version for those who prefer it, for accessibility and for spam filters, which sometimes look at whether both versions say the same thing. Send both.
How to build a simple HTML email template
1. Plan a single-column layout
One column reads well on every device. Start with a header (logo), a main content area, a call-to-action button and a footer. Resist the temptation to add many columns, which break on phones.
2. Write the basic structure
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Welcome</title>
</head>
<body style="margin:0;padding:0;background:#f4f4f4;">
<table role="presentation" width="100%" cellpadding="0" cellspacing="0">
<tr><td align="center">
<table role="presentation" width="600" cellpadding="0" cellspacing="0"
style="max-width:600px;width:100%;background:#ffffff;">
<tr><td style="padding:24px;font-family:Arial,Helvetica,sans-serif;
font-size:16px;line-height:24px;color:#222222;">
<h1 style="font-size:22px;margin:0 0 12px;">Hello there</h1>
<p style="margin:0 0 16px;">Thanks for joining us.</p>
</td></tr>
</table>
</td></tr>
</table>
</body>
</html>
The outer table fills the screen and centres the inner one. The inner table has a maximum width of 600 pixels and shrinks on small screens. The role="presentation" attribute tells screen readers that the table is only for layout.
3. Style with inline CSS
Write the fonts, colours and spacing as inline styles on each element. Many authors write the template with a style block and use a tool to move the rules inline before sending. Keep the code as small as you can, because very long messages may be cut off; see the next section.
4. Add images carefully
- Always set the
alttext and a width, so the layout holds when images are blocked. - Use images for logos and photos, not for important text. A message that is one big image is hard to read, does badly in spam filters and is useless to people who cannot see images.
- Keep files small. Use common formats.
5. Make buttons that work everywhere
A button in email is usually a link styled as a block, inside a table cell with a background colour and padding. Our article on links, buttons and mailto in HTML email shows the code and the pitfalls.
6. Think about the size of the code
Gmail clips messages whose HTML is larger than a limit, and shows a "view entire message" link. Anything below the cut, including the footer with the unsubscribe link, is hidden. Keep the HTML lean, remove comments and repeated styles, and test with a long message. See the footer advice in email footer examples.
7. Support dark mode
Many apps offer a dark theme and may change your colours. Use transparent logos, avoid pure white images with text baked in and check how the message looks in dark mode.
How to test an HTML email
- Validate the code for unclosed tags and missing attributes.
- Send test messages to accounts at Gmail, Outlook, Yahoo and Apple Mail, on desktop and on a phone.
- Turn images off and check that the message still makes sense.
- Check every link, including the unsubscribe link.
- Run a spam check. See the spam checker guide.
- Review accessibility: a clear reading order, enough colour contrast, alt text and a sensible language attribute.
Use a sandbox for development so that tests never reach real customers; see test email and staging environments.
How to send an HTML email
- From a mail app: Outlook and Gmail let you paste or insert HTML in various ways, but the controls vary. For regular sending, a template tool is easier.
- From an application: your code builds the message with an HTML part and a text part, and sends it through SMTP or an API. Libraries such as Nodemailer and the Python standard library support both; see our Nodemailer guide.
- From a sending service: store the template, merge in the data for each recipient and send. Email templates do this, and the email API and SMTP relay carry the message.
Whichever route you use, authenticate your sending domain; see authenticating your sending domain.
A short pre-send checklist
Before every send, confirm that the subject line and preview text read well together, that the sender name is one people recognise, that the plain-text version matches the HTML, that every link works and that the unsubscribe link is visible without scrolling through a clipped message. Check the message once more with images turned off, and once in dark mode. This takes a few minutes and prevents most of the problems readers notice.
Common mistakes
- Using modern layout techniques that break in Outlook.
- Building the whole message as one image.
- Skipping the plain-text version.
- Forgetting alt text and widths.
- Testing in one app only.
- Letting the message grow so large that Gmail clips it.
Build once, send everywhere Keep your templates in one place and merge data for each message you send.
References and further reading
Frequently asked questions
What is an HTML email?
It is a message whose body uses HTML markup for colours, images, buttons and layout. It is usually packaged with a plain-text version in a multipart message.
Why do HTML emails use tables?
Email apps render modern layout features inconsistently, and some versions of desktop Outlook use a word processor engine. Tables with inline styles are the most reliable way to build a layout.
Should I send plain text as well as HTML?
Yes. A plain-text version helps accessibility and reading preferences, and spam filters can look at whether both versions match.
How wide should an HTML email be?
A content column of about 600 pixels is common, set as a maximum width so that it shrinks on phones.
How do I test an HTML email?
Send tests to Gmail, Outlook, Yahoo and Apple Mail on desktop and phone, with images off and in dark mode, check all links and run a spam check.