HTML Email That Renders Everywhere: Tables, Inline CSS, Dark Mode
Write HTML email that renders in Gmail, Outlook, Apple Mail and mobile: table layout, inline CSS, the 600px rule, images, dark mode basics, and the API call.
Email clients are not browsers. Outlook on Windows renders HTML with Word's engine, Gmail strips your style block on some paths, and half of your readers are on a phone in dark mode. An email that looks perfect in Chrome can arrive as a single column of broken boxes. This guide gives you the small set of rules that make HTML email render consistently, and a template you can send through the API today.
Quick answer
Use nested tables for layout, a single 600px-wide centred container, inline CSS on every element, web-safe fonts with fallbacks, images with explicit width and alt text, no JavaScript, no forms, no background images you depend on, and a plain text alternative. Test in Gmail web, Gmail on Android, Apple Mail on iPhone and Outlook on Windows before you ship.
The rules
- Layout with tables, not flexbox or grid. Outlook does not support either. Set role="presentation" on layout tables for screen readers.
- Width 600px. It fits every desktop preview pane and scales down on phones with width="100%" and a max-width of 600px on the container.
- Inline all CSS. Gmail supports a style block in the head for many cases, but forwarded and some third-party clients drop it. Write the style attribute on the td and p tags themselves.
- Fonts: Arial, Helvetica, Georgia, Verdana, or a stack with a system font first and Arial last. Web fonts work only in Apple Mail and some Android clients.
- Images: absolute HTTPS URLs, explicit width and height, alt text, display:block to kill the gap under them. Do not put essential text in images; many clients block images by default.
- Buttons: a table cell with padding and background colour around a link. Not a button element (Outlook ignores it).
- No JavaScript, no video, no forms, no iframes. They are stripped or trigger spam filters.
- Keep the total HTML under 100 KB. Gmail clips larger messages with a "View entire message" link, which hides your footer and unsubscribe.
A minimal template that works
This is the skeleton behind most transactional emails: an outer table for the background, an inner 600px table for content, one column, everything inline.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width">
<meta name="color-scheme" content="light dark">
<meta name="supported-color-schemes" content="light dark">
<title>Order confirmed</title>
</head>
<body style="margin:0;padding:0;background:#f4f4f5;">
<table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="background:#f4f4f5;">
<tr><td align="center" style="padding:24px 12px;">
<table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="max-width:600px;background:#ffffff;border-radius:8px;">
<tr><td style="padding:32px;font-family:Arial,Helvetica,sans-serif;font-size:16px;line-height:24px;color:#18181b;">
<p style="margin:0 0 16px;">Hi Jane, your order <strong>#10482</strong> is confirmed.</p>
<table role="presentation" cellpadding="0" cellspacing="0">
<tr><td style="background:#2563eb;border-radius:6px;">
<a href="https://app.yourdomain.com/orders/10482" style="display:inline-block;padding:12px 20px;color:#ffffff;text-decoration:none;font-weight:bold;">View order</a>
</td></tr>
</table>
<p style="margin:24px 0 0;font-size:13px;color:#71717a;">Questions? Reply to this email.</p>
</td></tr>
</table>
</td></tr>
</table>
</body>
</html>Dark mode basics
Apple Mail, Outlook and Gmail on mobile may invert or adjust colours when the device is in dark mode. Three habits avoid the worst results. First, add the color-scheme and supported-color-schemes meta tags from the template so clients know you have thought about it. Second, never rely on a white background to make a dark logo visible; use a logo with a transparent background and a subtle outline, or a PNG that reads on both. Third, avoid pure black text on pure white; near-black (#18181b) on off-white (#f4f4f5) inverts more gracefully. You can add a prefers-color-scheme media query in a style block for the clients that honour it, but treat it as an enhancement, not a requirement.
Sending the HTML through the API
The API takes the whole document as the html field and, ideally, a text version alongside it. Minify whitespace if you like, but do not strip the doctype or meta tags.
const res = await fetch("https://api.oqumail.com/api/v1/emails", {
method: "POST",
headers: {
"Authorization": "Bearer " + process.env.OQUMAIL_API_KEY,
"Content-Type": "application/json"
},
body: JSON.stringify({
from: "orders@yourdomain.com",
to: order.email,
subject: "Order #" + order.number + " confirmed",
html: renderTemplate("order-confirmed.html", order),
text: "Hi " + order.firstName + ", your order #" + order.number + " is confirmed. View it: https://app.yourdomain.com/orders/" + order.number
})
});
if (!res.ok) throw new Error("send failed: " + res.status);Testing before you ship
- Send to your own addresses: a Gmail account, an Outlook.com account, and an iPhone. These three cover most of the rendering engines.
- Open the Gmail one on the web and on Android; open the Outlook one in the Windows desktop app if anyone on your team has it.
- Toggle dark mode on the phone and look again.
- Block images and confirm the email still makes sense from alt text and copy.
- Check the plain text version by viewing "Show original" in Gmail.
- Send from your real domain, not a test sender, so you also verify SPF, DKIM and DMARC pass. OquMail's delivery log shows the receiving server's response for each test.
Common questions
Can I use a CSS framework or MJML?
MJML compiles a simple markup into the table soup above and is a good choice if you send many templates. Regular CSS frameworks are not made for email and will break in Outlook.
Should transactional emails have a design at all?
A light one. A logo, one column, clear text, one button. Heavy designs slow rendering, increase size, and look like marketing to spam filters.
Why does my email look fine in Gmail but broken in Outlook?
Almost always a layout using div and CSS margins or padding on elements Outlook ignores. Move the spacing to td padding and the layout to tables.
Free business email on your own domain
OquMail gives you up to 15 mailboxes on your domain — free — with guided SPF/DKIM/DMARC, webmail, IMAP/SMTP for any mail app, and a send API. Most teams are live in under fifteen minutes. Start at oqumail.com.
Get started free