How to Build an HTML Email From Scratch in 2026
Building an HTML email that works across every client is one of the most frustrating challenges in web development. Here's the definitive guide to building emails that render reliably in Gmail, Outlook, Apple Mail, and everywhere else.
HTML email development requires defensive coding: structure all layouts using nested HTML <table role="presentation"> tags, inline all typography and spacing styles directly into style="..." attributes, use VML for Outlook background images and buttons, and keep your total file size strictly under 102KB to prevent Gmail message clipping.
Why email HTML is different
Web browsers implement a single, mostly-consistent CSS spec. Email clients don't. Outlook uses Microsoft Word's rendering engine. Gmail strips <style> blocks and rewrites class names. Yahoo adds its own wrapper styles. Each client has a different subset of CSS support. When you need a rule that only Gmail or only Outlook should see, that is client targeting CSS, not a second layout system.
The common denominator is HTML tables with inline styles. It's not elegant, but it's the only approach that works everywhere. If you prefer a higher-level abstraction, consider React Email or MJML, which compile to this table-based HTML automatically.
DOCTYPE and meta tags
Start with the HTML5 DOCTYPE and the meta tags that email clients actually use. The MSO-specific XML declarations are needed for VML support in Outlook:
<!DOCTYPE html>
<html lang="en" xmlns="http://www.w3.org/1999/xhtml"
xmlns:v="urn:schemas-microsoft-com:vml"
xmlns:o="urn:schemas-microsoft-com:office:office">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="color-scheme" content="light dark">
<meta name="supported-color-schemes" content="light dark">
<title>Your Email Subject</title>
<!--[if mso]>
<noscript>
<xml>
<o:OfficeDocumentSettings>
<o:PixelsPerInch>96</o:PixelsPerInch>
</o:OfficeDocumentSettings>
</xml>
</noscript>
<![endif]-->
</head>Table-based layout
Every email layout should be built with nested tables. The outer table centers the email, the inner table constrains the width. Always set role="presentation" on layout tables so screen readers don't announce them as data tables.
<!-- Outer wrapper , centers the email -->
<table role="presentation" width="100%" cellpadding="0" cellspacing="0"
style="background-color: #f6f6f6;">
<tr>
<td align="center" style="padding: 40px 20px;">
<!-- Inner container , max width 600px -->
<table role="presentation" width="600" cellpadding="0" cellspacing="0"
style="background-color: #ffffff; max-width: 600px; width: 100%;">
<tr>
<td style="padding: 30px;">
<h1 style="margin: 0 0 16px; font-size: 24px;
font-family: Arial, sans-serif; color: #333333;">
Welcome!
</h1>
<p style="margin: 0 0 24px; font-size: 14px; line-height: 1.6;
font-family: Arial, sans-serif; color: #666666;">
Thanks for signing up. Here's what to do next.
</p>
</td>
</tr>
</table>
</td>
</tr>
</table>Never use display: flex or CSS grid for email layout. Outlook ignores both entirely, and your email will collapse to a single column with no spacing.
Inline CSS
Gmail strips <style> blocks entirely. Your critical styles must be inline on each element. You can use <style> for progressive enhancement (like hover states or media queries), but never rely on it for layout or typography.
- Use longhand properties:
padding-top: 10pxnotpadding: 10px 20px - Set
bgcolorattribute ANDbackground-colorCSS (Outlook reads the attribute) - Always include
font-familyon every text element: inheritance is unreliable
Bulletproof buttons
A plain <a> tag with padding works in most clients, but border-radius breaks in Outlook. For universal support, wrap the link in a table cell and use VML conditionals for Outlook:
<!-- Bulletproof button , works in Outlook + all other clients -->
<table role="presentation" cellpadding="0" cellspacing="0"
style="margin: 24px 0;">
<tr>
<td style="background-color: #000000; border-radius: 6px;
padding: 12px 24px;">
<a href="https://example.com/action"
style="color: #ffffff; font-family: Arial, sans-serif;
font-size: 14px; text-decoration: none; display: inline-block;">
Get Started
</a>
</td>
</tr>
</table>
<!--[if mso]>
<!-- VML button for Outlook (supports border-radius) -->
<v:roundrect xmlns:v="urn:schemas-microsoft-com:vml"
href="https://example.com/action"
style="height:42px; width:160px; v-text-anchor:middle;"
arcsize="14%" fillcolor="#000000">
<w:anchorlock/>
<center style="color:#ffffff; font-family:Arial, sans-serif;
font-size:14px;">Get Started</center>
</v:roundrect>
<![endif]-->Responsive email
Media queries work in Apple Mail, iOS Mail, and some Android clients. Gmail on mobile ignores them. The safest approach is fluid design:
- Set
max-width: 600px; width: 100%on your container table - Use percentage widths for columns, not fixed pixel widths
- Add
style="max-width: 100%; height: auto;"on all images - Use media queries only as progressive enhancement
For a deeper dive, see our responsive email design guide.
Dark mode
Apple Mail, Outlook.com, and Gmail (Android) auto-invert colors in dark mode. You can control this with meta tags and a prefers-color-scheme media query:
/* In your <style> block (for clients that support it) */
@media (prefers-color-scheme: dark) {
.email-body {
background-color: #1a1a1a !important;
}
.email-text {
color: #e0e0e0 !important;
}
.email-heading {
color: #ffffff !important;
}
}
/* Apple Mail also respects this meta tag: */
/* <meta name="color-scheme" content="light dark"> */
/* <meta name="supported-color-schemes" content="light dark"> */Pre-send checklist
DOCTYPE set to HTML5 (not XHTML)
All styles are inline, no reliance on <style> blocks for critical layout
Layout uses <table> elements, not <div> with flexbox/grid
All layout tables have role="presentation"
Images have explicit width, height, and alt attributes
Font stack includes system fallbacks (Arial, sans-serif minimum)
Links have absolute URLs (no relative paths)
Background colors use both bgcolor attribute and CSS (Outlook reads bgcolor)
No CSS shorthand for padding/margin (use longhand properties)
Dark mode meta tags included in <head>
Tested in Outlook, Gmail, and Apple Mail at minimum
Gmail/MSO targeting (if used) is scoped, not treated as a global Outlook CSS failure
Total email size under 102KB (Gmail clips larger emails)
Essential follow-ups: Discover how to protect against Gmail 102KB message clipping, structure tables using Outlook ghost tables, and always pair your template with a clean plain-text email fallback.
Frequently Asked Questions
Why do HTML emails still require <table> elements for layouts?
Unlike modern web browsers, popular email clients (especially desktop Outlook for Windows, which uses the Microsoft Word engine) do not support CSS Flexbox or CSS Grid. HTML tables provide rock-solid dimensional boundaries that render uniformly across every inbox.
What is the role of 'role=presentation' on email tables?
When coding layout tables, adding role='presentation' tells screen readers to treat the table purely as visual styling rather than reading aloud column and row matrix coordinates, ensuring full accessibility for visually impaired subscribers.
Why does my email need to stay under 102KB?
Gmail desktop and mobile apps truncate any HTML email with raw code exceeding 102KB, replacing the rest with a '[Message clipped] View entire message' link. This breaks tracking pixels and hides critical footer unsubscribe links.
How do I make background images work in Outlook?
Outlook ignores standard CSS background-image declarations on HTML elements. You must use Microsoft Vector Markup Language (VML) tags like <v:rect> and <v:fill> wrapped in <!--[if mso]> conditional comments.
Check your HTML email against all 21 clients
Paste your HTML and get a compatibility report with per-client scores and actionable fix suggestions.
Preview your emailFree plan, 30 previews/day
- •Can I Email: Can I Email: CSS Support Across Email Clients
- •Litmus: Litmus: The Modern HTML Email Checklist
- •Email on Acid: Email on Acid: Email Coding Standards and Best Practices
- •Campaign Monitor: Campaign Monitor: The Ultimate Guide to CSS in Email
Reviewed by Philippe KAM · Last updated: Mar 4, 2026
Building next-generation email preview and QA infrastructure for developers. Focused on reverse-engineering rendering engines across Outlook (Word MSO & New Outlook), Gmail, and Apple Mail to eliminate email rendering bugs before dispatch.