HTML Import Overview
Harness lets you import your own HTML email design instead of building one in the editor (in the Email Builder, choose Import HTML). Email works very differently from a normal web page, though — inboxes like Gmail, Outlook, and Apple Mail strip out or ignore a lot of code that renders fine in a browser. Because of that, HTML that looks perfect on a website will often throw errors or display incorrectly when imported. This guide shows how to prepare an HTML file that imports cleanly and looks right in your recipients' inboxes.
This article covers the new CRM & Email experience (your left navigation shows CRM and Email). If your left nav shows Contacts and no Email item, this feature isn't part of your account.
Who this is for: anyone importing a custom HTML email. The first sections are plain-language and for everyone. The For Developers section further down has the technical requirements for whoever is building the file.
The 5 Things That Matter Most
Host your images online — don't embed them. Images must live at a web address (a URL). Images pasted or embedded directly into the HTML will not display.
Don't rely on background images. Some inboxes won't show them. Any text on top of one must still be readable if the image doesn't load.
Keep it simple: one column, about 600 pixels wide. Simple, single-column layouts are the most reliable everywhere.
Use standard fonts. Custom or downloaded fonts won't display; email falls back to a default.
Include an unsubscribe link and your mailing address. These are legally required on every email.
If you only remember these five, you'll avoid the most common problems.
Preparing Your Email
Images must be hosted online
Every image — your logo, photos, icons — needs to be uploaded somewhere public and referenced by its web address. If an image is embedded directly inside the HTML (often called a “base64” or “data” image), inboxes like Gmail will remove it and your reader will see a broken-image icon. This is the single most common reason a logo “disappears.” Host your images with your website provider, an image host, or a content delivery service, and make sure each address starts with https://.
Background images are unreliable
A color or photo placed behind text (a “background image”) may simply not appear in some inboxes, especially older Outlook and parts of Gmail. That's normal and expected. The safe approach:
Treat background images as decoration, not as something essential.
Always set a solid background color behind them, so if the image doesn't load, the section still looks intentional.
Make sure any text over the image is still easy to read against that solid color alone.
If an image is important (like your logo or a key photo), place it as a regular image, not a background.
Keep the layout simple
Design for a single column, roughly 600 pixels wide. Most people read email on their phones, and a simple column adjusts gracefully to small screens. Complex multi-column web layouts often break in email.
Use standard fonts
Stick to widely available fonts (for example Arial, Helvetica, Georgia, Times New Roman). Custom brand fonts and downloaded web fonts don't work in most inboxes — the email will quietly substitute a default font, which can change how your design looks. If a specific font is essential for a headline, save that headline as an image instead.
Links, buttons, and required footer items
Text links and buttons work normally.
Every email must include an unsubscribe link and your organization's physical mailing address in the footer. This is a legal requirement (CAN-SPAM), and emails without them can be blocked.
Preview text is set in Harness, not in your HTML
The short preview line that appears next to the subject in the inbox is set inside Harness when you send, not in your HTML file. You don't need to add it to your design.
Personalization and dynamic content
Merge tags and personalization codes (like {{first_name}}) and any dynamic or conditional content are not supported on imported HTML. Write all text as final, static copy. Anything that looks like a code will be sent to recipients exactly as typed.
Keep the file small
Keep the whole HTML file under about 100 KB. Gmail cuts off (“clips”) emails larger than that. Hosting your images online — rather than embedding them — is the easiest way to stay small.
For Developers — Technical Requirements
Build the email as traditional, table-based, inline-styled HTML.
Structure
Use tables for all layout (
role="presentation"). No<div>flow layout, no flexbox, grid,float, orposition.Fixed content width of ~600px; single column.
Space with
<td>padding, not CSSmargin.Headings: use
<h1>–<h3>only.
Styling
Inline every style. Don't depend on a
<style>block or external stylesheet.Do not use:
@mediaqueries,flex/grid/position/float,transform,transition,animation, CSS gradients, CSS variables, or@font-face.Fonts: web-safe stacks only (e.g.
Arial, Helvetica, sans-serif).
Images
Absolute
https://URLs only. Nodata:/base64 images.Every
<img>needs awidthattribute,alttext, andstyle="display:block;border:0;".Export at ~2× the display size for sharpness on retina screens; scale down via the
widthattribute.
Background images
Place on a
<td>, always paired with a fallbackbackground-color.Text over a background image must remain legible on the fallback color alone.
Include Outlook VML fallback markup if the background is important for the design.
Buttons
Build as an
<a>inside a padded table cell with a solid background color and high-contrast text. Add an Outlook (MSO/VML) fallback for reliable rendering.
Do not include
<script>,<iframe>,<form>,<input>,<video>,<svg>,<canvas>, embeds, or any interactive/JavaScript-driven widgets (countdown timers, accordions).Merge tags / personalization / conditional logic.
Size: keep the HTML under ~100 KB (external images don't count toward this).
Common Problems and How to Fix Them
What you're seeing | Why | Fix |
Logo or an image shows as a broken icon | The image was embedded in the HTML instead of hosted | Upload the image online and link to it with an |
A background image disappeared (color still shows) | Some inboxes don't render background images | Expected — keep the fallback color and make sure text is readable without the image; use a regular image if it's essential |
Email looks broken or misaligned in Outlook | Outlook ignores modern CSS | Use table-based layout and inline styles; add Outlook fallbacks for buttons/backgrounds |
Email gets cut off in Gmail (“view entire message”) | File is over ~100 KB, usually from embedded images | Host images online instead of embedding; reduce file size |
Fonts look different than designed | A custom/web font isn't supported | Use a standard font, or save the styled text as an image |
Layout doesn't stack well on mobile | Multi-column or fixed web layout | Design a single ~600px column |
A | Personalization tags aren't supported on import | Replace with final static text before importing |
Before You Import — Quick Checklist
All images are hosted online with
https://URLs (nothing embedded/base64)Background images have a fallback color, and text over them is readable without them
Layout is a single column, ~600px wide
Only standard fonts are used
Every image has alt text
Footer includes an unsubscribe link and your mailing address
No personalization tags or dynamic code — all text is final
No forms, videos, scripts, or interactive widgets
File is under ~100 KB
What Happens After You Import
When you import your HTML, Harness reads your design and rebuilds it inside the editor. Very complex or unsupported code may be simplified or adjusted during this step, so after importing:
Preview your email in the editor.
Send yourself a test and check it on both desktop and a phone.
If something looks off, review the checklist above — most issues trace back to one of those items.