Settingsbeginner

FAQ — Why didn't my template render right?

Five common rendering problems and what causes them: layout broken in specific clients, missing images, merge tags showing as literal text, dark-mode legibility, mobile breakage.

Published May 13, 20264 min read

FAQ — Why didn’t my template render right?

The five most common email rendering problems and how to diagnose them.

1. Layout looks fine in editor, broken in Outlook (or another client)

Email clients render HTML inconsistently. Outlook in particular uses Microsoft Word’s rendering engine for some versions, which doesn’t handle modern CSS the same way Gmail or Apple Mail does.

Common culprits:

Nested columns. A 2-column layout inside a 1-column section is fine. Two levels of nesting often breaks. Stick to one level.
Heading blocks for body text. Heading blocks have specific size/weight defaults; some clients ignore your overrides. Use Text blocks with rich-text headings instead.
Aggressive padding. Margin and padding values that work in modern clients sometimes get dropped in Outlook. If a section’s spacing collapses, reduce it.

Diagnostic: send the template to a test inbox you’ve set up specifically in the problem client. Litmus and Email on Acid let you preview in dozens of clients without needing accounts on each.

2. Images don’t appear

Two scenarios:

Images blocked by default in the recipient’s client (Gmail and Outlook both do this for unknown senders). Without images, the email shows alt text. Make sure every Image block has descriptive alt text — it’s the user-readable version when the image doesn’t load.
Image URL is invalid or behind auth. If the URL requires login, customers can’t reach it. Use publicly-accessible URLs or upload directly to Email Studio.

Diagnostic: open the delivered email in a browser-based mail client (e.g. Gmail web), right-click an image, “open in new tab” — does it actually load?

3. Merge tags appear as literal `{{...}}` instead of values

The merge tag’s path doesn’t resolve. Causes:

Typo in the path. {{contact.first_name}} is correct; {{contact.firstname}} (no underscore) is not. Check the merge tag picker for the exact path.
Field doesn’t exist. Custom fields that were renamed change keys; old templates referencing the old key now produce literal output.
Sending context doesn’t include the field. A template referencing {{conversation.subject}} sent without a conversation context (e.g. a User Invitation send) renders as literal text.

Diagnostic: check Manual Executions for the rule that sent the email — the action’s payload includes the resolved values. If a merge tag shows up as the literal {{...}} in the payload, the path is broken at template time, not delivery time.

4. Email is unreadable in dark mode

Common when the template was designed only with the light-mode preview. Specific risks:

Light grey body text that becomes light-grey on dark, near-invisible.
Hard-coded white background on inner sections that become a stark white box on a dark email. Either set background to transparent (so it inherits the client’s dark-mode background), or use a slightly off-white that doesn’t look out of place.
Logo with hardcoded brand colors that don’t pop against dark. Most logos work in both modes; some need a dark-mode variant.

Diagnostic: flip Email Studio’s preview to dark-mode and walk through the template. Anything that has lower contrast in dark mode is a candidate to fix.

5. Mobile layout breaks

Mobile clients (iPhone Mail, Gmail mobile) render at narrower widths. Things that work on desktop sometimes don’t on mobile:

Multi-column layouts that stack vertically when the screen narrows. Atender’s column blocks generally do this correctly, but custom HTML or images sized at fixed widths don’t.
Buttons cut off because their padding pushes them past the viewport width.
Long URLs in plain text that overflow the line.

Diagnostic: Email Studio’s mobile preview is the first check. After that, send a test to your phone and read it as a customer would.

A general practice that prevents most issues

Test before going live. Send the template to:

Your own Gmail (web)
Your own Outlook (web or desktop)
Your own iPhone or Android Mail app

If the template looks fine in all three, it’ll render acceptably for the vast majority of customers. Edge-case clients will have rare issues you can address as they’re reported.