Edit

Troubleshooting: Fix email rendering issues

Rendering emails exactly as designed is critical for protecting the company's brand. However, email clients vary widely in how they interpret standard HTML. To address these differences, the email designer applies a post‑processing step that modifies the HTML to work around known limitations in various email clients. As a result, the final email HTML can be more complex than expected. While this process ensures consistent rendering across most email clients, some limitations can't be fully resolved.

This article documents known limitations and recommended mitigations. As email clients evolve, some issues may get fixed or new issues may be introduced anytime. We'll update this article as we learn about these changes.

To reduce issues, we recommend using the out-of-the-box layouts and elements provided by the email designer whenever possible. Most issues occur when customers replace or modify generated HTML with their own custom code. We don't support issues caused by custom HTML. Customers must validate and test their custom code across various email clients and fix issues using the guidance in this article.

All email clients

Dark mode changes email colors unexpectedly

Most email clients automatically adjust email colors when the recipient's device is set to dark mode. This behavior varies by client and can't be controlled from the email editor. Any color changes that occur in dark mode are expected behavior of the email client.

Suggested solution

If you want to prevent color changes in dark mode, use background images instead of background colors. Background images are generally preserved by email clients in dark mode, whereas background colors are often inverted or replaced.

Custom content blocks aren't supported out of the box

Custom content blocks aren't supported by default. When custom HTML code is used in a content block, the customer is responsible for ensuring that the HTML renders correctly across email clients.

Suggested solution

At this time, there's no known solution for this issue.

Email appears black

Note

This issue occurs only when you modify or replace the HTML generated by the email designer with your own custom HTML with syntax errors.

When an email contains invalid HTML or syntax errors, some email clients may fail to render the content correctly and display the email body as a solid black area. This issue has been observed in email clients such as Outlook (Classic) and Yahoo Mail. This behavior is caused by how email clients handle malformed HTML and isn't controlled by the email designer.

Suggested solution

Ensure that the email HTML doesn't contain syntax errors introduced by manual editing. Pay special attention to unclosed tags, invalid nesting, or malformed attributes. If the issue persists, consider recreating the email using the email designer and its drag and drop elements, which generate validated HTML and reduce the risk of client specific rendering failures.

Gmail

Email content is truncated

Gmail automatically truncates email messages that exceed a size limit.

Suggested solution

Ensure email size is within the size limits supported by Gmail.

  • Reduce the size of images and avoid embedding large assets.
  • Simplify the email layout and structure.
  • Use text based content instead of images where possible.

Outlook (Classic)

Margins and padding render inconsistently

Note

This issue occurs only when you modify or replace the HTML generated by the email designer with your own custom HTML, overriding the code intended by the email designer to handle this correctly.

Outlook (Classic) uses a Word-based HTML processing engine that has limited support for standard CSS margins and padding on HTML elements. This can cause spacing to appear differently in Outlook compared to web-based email clients.

Suggested solution

To create correct spacing, add padding to the td elements of the tables that define the layout. For text, buttons, and other drag-and-drop elements, tables are added automatically during post-processing to create the appropriate spacing.

Background images don't render

Note

This issue occurs only when you modify or replace the HTML generated by the email designer with your own custom HTML, overriding the code intended by the email designer to handle this correctly.

Outlook (Classic) doesn't natively support CSS background images on sections and columns.

Suggested solution

Background images are rendered in Outlook using VML (Vector Markup Language) elements, which require a pre-calculated height for each section or column. This is handled automatically during post-processing.

Important

Background colors that use transparency are treated as background images in Outlook (Classic) and are subject to the same rendering limitations. To avoid this, use a fully opaque color instead of a transparent one.

Be aware of the following additional limitations when using background images in Outlook:

  • Dynamic values in content: When your email contains dynamic text (for example, {{FirstName}}), the height calculation may not be precise, which can cause the background image to be cut off or misaligned.
  • Rounded corner buttons: Buttons with rounded corners placed on a section or column with a background image will have their border radius removed automatically, because VML-based buttons and VML backgrounds aren't compatible.

Line height renders larger than in web clients

Note

This issue occurs only when you modify or replace the HTML generated by the email designer with your own custom HTML, overriding the code intended by the email designer to handle this correctly.

Outlook (Classic) renders line height larger than web-based clients, resulting in more vertical space between lines of text than intended. Additionally, numeric line-height values (for example, line-height: 1.5) aren't supported.

Suggested solution

  • Apply line-height to the <p> element, not to <span> elements. When set on a <span>, a visible line can appear between sections in some cases.
  • Use percentage values for line height. For example, replace line-height: 1.5 with line-height: 150%. This conversion is handled automatically during post-processing.

White lines appear between sections

Note

This issue occurs only when you modify or replace the HTML generated by the email designer with your own custom HTML, overriding the code intended by the email designer to handle this correctly.

Thin white lines can appear between email sections in Outlook (Classic). This is caused by the Word-based HTML processor Outlook (Classic) uses and is most commonly triggered by nested table layouts or by setting line-height on <span> elements instead of <p> elements.

Suggested solution

This is handled automatically during post-processing by adding an empty <p> element with height 0, or by adding additional rows and cells to the nested tables. To avoid triggering this issue in your own HTML, apply line-height to <p> elements rather than <span> elements.

Note

This issue occurs only when you modify or replace the HTML generated by the email designer with your own custom HTML, overriding the code intended by the email designer to handle this correctly.

If a linked image has incorrect HTML element ordering—specifically, when the <a> element wraps the outer <div> instead of the inner <img> element—the image may render out of place or become misaligned.

The broken structure looks like this:

<div data-editorblocktype="Image">
  <a href="...">
    <div class="imageWrapper">
      <img src="..." alt="...">
    </div>
  </a>
</div>

The correct structure is:

<div data-editorblocktype="Image">
  <div class="imageWrapper">
    <a href="...">
      <img src="..." alt="...">
    </a>
  </div>
</div>

Suggested solution

Fix the HTML directly to ensure the <a> element wraps the <img> element rather than the outer <div>. Alternatively, remove the link from the image in the designer and then reapply it.

A gap appears between sections when forwarding

When an email is forwarded from Outlook (Classic), the HTML is pre-processed before sending, which can introduce gaps between sections.

Suggested solution

The email designer handles this automatically. If you're using your own custom code, add an additional row to outer section tables using the following VML conditional comment:

<!--[if gte mso 9]>
<tr style="padding: 0px; mso-line-height-rule: exactly; line-height: 1px; background-color: rgb(0, 0, 0);" height="0">
  <td>&nbsp;</td>
</tr>
<![endif]-->

Note

As a side effect of this workaround, sections that have no padding may still show a small gap when the email is forwarded.

Rounded buttons are broken when forwarding to Gmail

When an email containing rounded-corner buttons is forwarded from Outlook (Classic) to a Gmail web client, the button rendering breaks. This is caused by how VML elements are used to render rounded buttons in Outlook.

Suggested solution

Remove the border radius from buttons before sending if the email is likely to be forwarded. Buttons without a border radius will render correctly after forwarding.

Long words break section width

Outlook (Classic) doesn't support selectively breaking only long words; it supports either breaking all words or none. Long words or URLs that don't break can cause the width of a section to expand beyond its intended size.

Additionally, using &nbsp; (non-breaking space) instead of a regular space character causes Outlook (Classic) to treat the whole phrase as one unbreakable word, further widening columns.

Suggested solution

Add the style word-break: break-all; to the <p> element containing the long word or link. The &nbsp; issue is resolved automatically during post-processing.

Dynamic images cause table width to expand

When the width or height of an element exceeds the table or cell width, Outlook expands the table to fit the content. This is especially problematic with dynamic images that use personalization placeholders in the URL, because the actual image size is unknown during post-processing.

Suggested solution

In the designer, set the image width to 100% instead of auto. This prevents Outlook (Classic) from expanding the table when the image dimensions can't be determined in advance.

Unwanted underline appears on buttons and linked text

Outlook (Classic) can apply a default underline to anchor (<a>) elements, resulting in buttons and linked text appearing underlined unexpectedly.

Suggested solution

Add the following CSS to the email's default styles to remove the default underline while preserving intentional underlines applied through the toolbar:

a { text-decoration: none; }
u a { text-decoration: underline; }

Underline color on linked text doesn't match text color

In Outlook (Classic), the underline on linked text may appear in a different color than the text itself.

Suggested solution

To ensure the underline color matches the text color, follow these steps in order:

  1. Select the text.
  2. Apply the underline style.
  3. Add a hyperlink to the selected text.
  4. Set the font color on the selected text.

Applying the color as the last step ensures that both the text and the underline inherit the same color.

Custom bullet styles don't render

Custom bullet types (for example, square bullets) may not render correctly in Outlook (Classic) if only a CSS class is used to define the bullet style.

Suggested solution

In addition to setting the CSS class, include the type attribute directly on the <ul> element:

<ul class="square" type="square">
  <li>Item</li>
</ul>

Vertical line appears in the layout

A vertical line may appear in the email layout in Outlook when a direction: rtl CSS style or dir="rtl" attribute is applied to a container element.

Suggested solution

Instead of setting direction: rtl on the container element, apply it only to the text elements inside the container. Alternatively, add the following scoped style to the email's <style> tag:

[data-container="true"] div { direction: rtl; }

Background image height is inaccurate when dynamic text is present

When a section or column uses a background image and also contains dynamic text (for example, {{FirstName}}), the pre-calculated height used to render the VML background image can't account for the actual height of the dynamic content. This can cause the background image to be clipped or misaligned.

Suggested solution

Currently, there's no known solution for this issue.

Divider height is limited to 10px

Outlook limits table borders to a maximum of 10px. Because the divider element uses a table border, the maximum divider height is also capped at 10px.

Suggested solution

Currently, there's no known solution for this issue.

Background images on sections and columns are broken after forwarding

Background images that render correctly in the delivered email may appear broken after the email is forwarded from Outlook desktop. Outlook modifies VML styles during the forwarding process, which can break the layout.

Suggested solution

Currently, there's no known solution for this issue.

Bullet points missing in Litmus preview (Outlook Classic 2016)

Bullet points may not appear when previewing emails in Litmus for Outlook Classic 2016.

Suggested solution

Add the following MSO conditional style to the <head> of the email. See the official Litmus guidance for more details.

<!--[if (gte mso 9)|(IE)]>
<style>
  li {
    margin-left: 27px !important;
    mso-special-format: bullet;
  }
</style>
<![endif]-->

Custom font fallback not applied

When a custom font is used that Outlook (Classic) doesn't support, it may not fall back to the specified fallback font.

Suggested solution

Add the following MSO conditional style block to the <body> of the email, replacing Arial with your preferred fallback font:

<!--[if mso]>
<style type="text/css">
  body, table, td, h1, h2, h3, h4, h5, p, span {
    font-family: Arial !important;
  }
</style>
<![endif]-->

If your email uses a custom @font-face declaration, also add the mso-font-alt property to specify the fallback:

@font-face {
  font-family: Ambit;
  font-display: swap;
  src: url("https://example.com/fonts/ambit-regular.otf");
  mso-font-alt: 'Arial';
}

Outlook mobile

Table layouts aren't responsive

Note

This issue occurs only when you modify or replace the HTML generated by the email designer with your own custom HTML, overriding the code intended by the email designer to handle this correctly.

Table-based layouts may not reflow correctly for smaller screens in Outlook mobile applications. Additionally, iOS Outlook requires <th> elements instead of <td> elements to enable responsive table layouts.

Suggested solution

Ensure the email uses the latest responsive styles. For iOS Outlook, use <th> instead of <td> in table layouts.

Bell.net

Outlook conditional comments and their content are removed

Note

This issue occurs only when you modify or replace the HTML generated by the email designer with your own custom HTML, overriding the code intended by the email designer to handle this correctly.

The Bell.net email client strips Outlook-specific conditional comments (<!--[if ...]>) along with any HTML elements inside them. This can cause layout issues when those comments contain elements needed for correct rendering.

Suggested solution

Use table-based HTML layouts instead of <div>-based layouts. This reduces the need for Outlook conditional comments. As a result, Outlook conditional comments for tables aren't added when spacing is set to 0.

Orange mobile

Div-based layouts aren't supported

Note

This issue occurs only when you modify or replace the HTML generated by the email designer with your own custom HTML, overriding the code intended by the email designer to handle this correctly.)

The Orange mobile email client supports only HTML3 and table-based layouts. Emails that use <div>-based layouts won't render correctly.

Suggested solution

At this time, there's no known solution for this issue.

T-online

T-Online.de presents specific challenges for HTML email rendering. The following capabilities aren't supported (or supported with limitations):

  • Background images
  • Border Radius
  • Checkbox/radio button
  • Classes
  • CSS attribute selector
  • HTML5 video
  • Media query
  • Styled ALT text
  • Style in head
  • Transitions/keyframe animation
  • Web fonts

Layout & Responsiveness

  • Fixed width constraint: Emails wider than 800px may be scaled down or partially hidden, especially when the viewport narrows below 645px. Since T-Online.de doesn't support media queries, responsive designs relying on them won't function as intended.
  • Table-based layouts: Utilize table structures instead of <div> elements for layout purposes. This approach ensures better compatibility across various email clients, including T-Online.de.

CSS and styling limitations

  • Media queries: Not supported. Avoid relying on them for responsive designs. Features like Wrap on mobile, or Hide on desktop won't work.
  • Background images: Not supported. Refrain from using background images for essential content.
  • Custom fonts: Not supported. Specify fallback fonts when using Custom fonts, to make sure emails render properly in T-online.de.
  • Advanced CSS features: Properties like border-radius, transitions, and animations aren't supported. Rounded corners might not work. Design with basic CSS to ensure compatibility.
  • Cascading: Doesn't always work properly. For example, in this case, the text is still black:
div {
 color: red;
}

<div>
 <p><span>Use red color</span></p>
</div>

The email designer handles this case using Themes, where the color is specified on the <p> level.

p {
 color: red;
}

<div>
 <p><span>Use red color</span></p>
</div>
  • Line-height on <span> tags: This causes text to collapse to 0px height. Use instead set line-height on <p> tags. (The email designer automatically handles this correctly.)
  • Line breaks in links: T-Online.de may misinterpret links that contain line breaks, leading to rendering issues. Ensure that all hyperlinks are continuous and free of line breaks to prevent display problems.

HTML validation and security filters

  • Strict HTML parsing: T-Online.de employs rigorous HTML validation. Invalid or non-standard HTML can result in the entire email being blocked or displayed incorrectly. Ensure that your HTML code is clean and adheres to standards.
  • Unsupported elements: Elements like <xml> aren't supported and can cause rendering issues. Avoid including such elements in your emails.

Other recommendations

  • Use the email designer toolbox: Avoid manual HTML changes. The email designer is able to handle many limitations correctly (thanks to the Themes capability) and create emails that render correctly on most email clients.
  • Use inline CSS for custom emails: If you're not using the email designer toolbox, consider applying all CSS inline to ensure consistent styling.
  • Limit email width: Keep the maximum width of your email to 600–800px to prevent horizontal scrolling or content clipping.
  • Avoid background images: Use solid background colors instead of images to ensure visibility across clients.
  • Provide web version links: Include a link to a web-hosted version of the email for users who may experience rendering issues.
  • Last updated on