Guides
How to build an HTML email that looks right in every inbox
Outlook draws email with a word processor, Gmail clips long messages and dark mode flips your colors. Here is how to build an email that survives all three.
MD Rakib Shekh · Founder & Lead Architect
· 7 min read

On this page
You design a newsletter that looks perfect in your browser and send it. Then a customer replies with a screenshot: squashed buttons, a missing logo and the bottom half cut off. Email isn't the web. Every inbox draws HTML its own way, and some are very old-fashioned. Here's what goes wrong, and how to build an email that holds up.
Why email HTML is different
A web page runs in a modern browser. An email runs inside an email app, and each app decides which HTML and CSS it will allow. Some strip styles. Some block images. One popular desktop app uses a word processor to draw the message.
So email design follows a few old-school rules: layouts built from tables, important styles written inline, a fixed and fairly narrow content width, and no JavaScript at all.
Outlook: the hardest inbox
Classic Outlook for Windows uses Microsoft Word as its rendering engine (Litmus). Word understands only part of modern CSS. In practice:
- Outlook ignores most styles on div tags, including widths and padding, so content belongs in tables.
- It strips padding and margins from images. Put the spacing on the table cell around the image instead.
- Background images, rounded buttons and gradients need extra Outlook-only code called VML.
The new Outlook for Windows is built on Outlook's web app and uses a browser engine instead of Word, Litmus notes. The older desktop versions won't disappear overnight, so plan for both. Outlook for Mac uses WebKit and behaves much like Apple Mail.
Gmail: styles, clipping and images
Gmail supports style blocks in the email, class and ID selectors, and media queries, according to Google's developer docs. It may ignore properties it doesn't support, so keep key styles inline as a backup.
Gmail's biggest trap is size. It clips messages larger than 102KB and hides the rest behind a "View entire message" link (Mailchimp). The hidden part often includes your footer and unsubscribe link. Common causes are hidden formatting code that comes along when you paste from other apps, and simply too much content. Linked images are loaded from a server, so their file size doesn't count; the code around them does.
Gmail shows images by default, but it may hold them back for senders it finds suspicious (Gmail Help). Images embedded directly in the code (base64 or "data:" images) don't display in Gmail or in most versions of classic Outlook for Windows, according to tests by Can I email. Host your images online and link to them.
Dark mode
Email apps handle dark mode in three different ways (Litmus):
- No change. The email shows exactly as you designed it.
- Partial invert. Light backgrounds turn dark and dark text turns light. Areas that are already dark are usually left alone.
- Full invert. Both light and dark areas may be flipped. Litmus lists the Gmail app on iOS and Outlook for Windows among these.
You can't control them all, so design to survive:
- Logos: a transparent PNG with dark lettering can vanish on a dark background. Litmus suggests adding a translucent outline around it. A solid light shape behind the logo also works.
- Text in images: keep important words as live text. An image can't change color for dark mode, and it might be blocked anyway.
- Preview it. Pagestro's email builder has a Gmail dark mode preview, so you can check logos and colored sections on a dark background. It's a simulation, so confirm with a real test send.
Images that fail gracefully
Expect some readers to see your email without images at first. Classic Outlook blocks automatic picture downloads by default (Microsoft Support).
- Write alt text for every image. It's what people see when images are blocked, and what screen readers read aloud.
- Don't build the whole email as one big picture. If it's blocked, the email is blank.
- Make buttons from HTML, not images, so they still show and can be tapped.
- Shrink images before you upload them with Compress Image. Our guide to compressing images for your website explains the settings.
Design for phones
Use a single column that stacks neatly, text big enough to read without zooming, and buttons big enough to tap with a thumb. Media queries can adjust the layout for small screens, but make sure the email still reads well in apps that ignore them.
Let a builder do the hard parts
Hand-coding all of this takes time. Pagestro's email builder uses MJML, an open-source framework made for responsive email (MJML docs). It turns your design into table-based HTML built for email apps, including Outlook and Gmail.
Step 1. Pick a template or a blank canvas, or import HTML or MJML you already have.
Step 2. Drag in headings, text, images, buttons and columns, then click anything to edit it. Merge tags such as first name or the unsubscribe link are in the text toolbar.
Step 3. Check the phone preview and the Gmail dark mode preview.
Step 4. Run the pre-send checks. They flag emails Gmail would clip, images without alt text, embedded images, empty or insecure (http) links, a missing subject or preview text, and a missing unsubscribe link on marketing email.
Step 5. Copy the HTML, or download it as .html or .mjml, and add it to the email service you send with.
You don't need an account to design and export. Sign in to save designs and send test emails to yourself. How many you can save and send depends on your plan (see pricing). Pagestro doesn't send campaigns. You send them from the email service you already use.
Test before you send
Previews help, but nothing beats a real inbox.
- Send tests to the apps your readers use: at least Gmail, Outlook and Apple Mail, on a computer and on a phone.
- Check each one in dark mode.
- Click every link and button.
- Turn images off in one app and read the email again.
- For big sends, testing services such as Litmus show previews across many email apps at once.
Marketing emails have legal rules too. In the US, the CAN-SPAM Act requires a clear way to opt out and your valid postal address (FTC). Big mailbox providers also have their own sender rules: see our guide to email sender requirements for Gmail, Yahoo and Outlook. This is general information, not legal advice.
Frequently asked questions
Why does my email look different in Outlook?
Classic Outlook for Windows draws email with Word's engine, which supports only part of modern HTML and CSS. Table-based layouts, like the ones MJML produces, hold up best.
What is Gmail clipping?
Gmail hides the end of any message larger than 102KB behind a "View entire message" link. Keep the code lean and check the size before you send. Pagestro's pre-send checks warn you when an email is over the limit.
Should headlines be images or live text?
Live text. It shows when images are blocked, adapts to dark mode and can be read by screen readers.
Can I use the HTML in Mailchimp or another platform?
Yes. Export the HTML and paste or upload it wherever your platform accepts custom code. If your platform writes merge tags in a different format, rename them.
Does Pagestro send my emails?
No. The email builder is for designing and testing. You send the campaign from the email service you already use.
- HTML email
- Email marketing
- Design

Written by
MD Rakib Shekh
Founder & Lead Architect
Founder of Pagestro & UIXport. Specializing in WebAssembly browser tools, PDF processing, and high-performance design workflows.





