How to Create Responsive Email Templates in Braze

To create responsive email templates in Braze, decide first whether you need screen-size CSS, which belongs in the HTML editor, or row-level show and hide, which the drag-and-drop editor handles. Build a narrow single column that still reads well if a client drops your styles, set explicit background colours for dark mode, then test in a fixed order.

‍

Key Takeaways

• A responsive template still reads well on a phone when the email client strips part of your CSS.
• Choose the editor by the control you need: rows with Hide on mobile in drag-and-drop, screen-size CSS in the HTML editor.
• Keep a shared mobile and desktop template under 500 pixels wide, built with nested tables and inline styles.
• Set a background colour on the outer container and every major section so dark mode doesn't hide content.
• HTML returned from Connected Content isn't inlined, so return it with styles already inline.
• Test in a fixed order: mobile view, Dark mode, preview as a user, Inbox Vision, then real devices.

‍

What makes an email template responsive in Braze?

A responsive template is one that still reads well on a phone when the email client ignores part of your CSS. Media queries help, but they're the layer most likely to be removed. The base layout has to carry the message on its own.

Braze's email guidance points the same way. It suggests mobile-first responsive patterns that don't rely solely on media queries for mobile rendering. Treat that sentence as the brief for every template, and the rest of this post follows from it.

‍

Which editor should you build responsive templates in?

Pick the editor by the kind of control you need, because the two handle mobile differently. The table sets out what Braze documents for each.

‍

The drag-and-drop editor suits teams that want marketers to build safely within a fixed set of layouts. The HTML editor suits templates that need screen-size rules, such as tighter padding on phones. Choose one per template family and keep to it, because rebuilding a template in the other editor later is close to starting over.

‍

Why should the layout work without media queries?

Some clients remove your styles before the reader sees anything. Braze notes that if an email contains too much CSS, Gmail may remove the entire style block. For non-Gmail accounts in the Gmail app, CSS in the head isn't supported at all.

The visible symptom is an email that displays in desktop view inside the Gmail app. Braze lists this outcome directly, and it's why the fallback layout matters more than the media queries.

Four documented rules keep that fallback sound.

1. Keep the width under 500 pixels if one template serves both mobile and desktop.
2. Use nested tables for layout, not div tags, and avoid absolute or relative positioning.
3. Use inline styles for your CSS rather than relying on a style block.
4. Don't set heights and widths on images, because that can leave white space in a degraded email.

‍

Treat the style block as an enhancement. If deleting it leaves a readable single column, the template is responsive in the sense that matters.

‍

How do you keep dark mode from breaking the template?

Braze documents that you don't need separate light and dark layouts, because email clients and devices can apply their own dark theme. The risk is what that theme does to colours you didn't set. It may invert colours or hide backgrounds if the outer container and major sections have no explicit colours.

The fix is specific. Set a background colour on the outer container and on each major section, instead of relying on background images alone for light areas. Then turn on Dark mode in Preview and Test in the drag-and-drop editor, and check every section, not just the hero.

Low-contrast text is at particular risk, since Braze notes that some clients invert it in dark mode. If a line of body copy is only readable on white, assume a dark theme will make it hard to read and give it more contrast from the start.

‍

Where do Content Blocks and Connected Content change the result?

Shared blocks bring their own width. Braze recommends matching the Content Block width to the email template width. A block built for a wider template will break the narrow column you designed around.

Preview can also mislead here. When you template a Content Block with Liquid, Braze notes that mobile media queries in the block may not apply in the preview the same way. Check those blocks on a real device before you trust the preview.

Connected Content needs its own styling. CSS inlining runs before Connected Content is evaluated, and HTML returned from Connected Content isn't passed through the same inlining step. Any HTML your endpoint returns should arrive with its styles already inline.

‍

In what order should you test a responsive template?

Test in this order, because each step is cheaper than the next and catches a different fault.

1. Toggle the mobile view in the editor while you build, and fix layout faults as they appear.
2. Turn on Dark mode in Preview and Test, and check every section for lost backgrounds or text.
3. Preview as a user with and without each personalised value, so empty fields don't collapse a row.
4. Run Inbox Vision to see the email across web, application and mobile clients, including dark and light mode.
5. Send a test to real phones on the clients your audience uses most.

‍

Inbox Vision has two constraints worth planning for. Your company has a limit on previews, so save it for templates that have passed the first three steps. It also doesn't support messages with abort logic, and Braze advises adding default values to the Liquid before you run it.

‍

Which failures should a template review look for?

Give the common failures short names, so a reviewer can flag one in a comment instead of describing it. A desktop fallback is a phone showing the desktop layout because the style block was dropped. Its check is reading the template with the style block deleted.

A vanishing paragraph is body copy that disappears under a client's dark theme. Its check is the Dark mode toggle plus at least one dark theme client in Inbox Vision.

A wide block is a shared Content Block built for a different template width. Its check is comparing the block's width setting with the template's before inserting it. An uninlined fragment is Connected Content HTML that arrives without inline styles, and its check is a test send with the endpoint returning its real markup.

Put the four names in your review checklist, next to the testing order above.

‍

What does a mobile-first skeleton look like?

This skeleton follows the documented rules: nested tables, inline styles, a column under 500 pixels and explicit background colours. It's an illustration, not a tested template, so run it through the steps above before use.

<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="background-color:#ffffff;">
  <tr>
    <td align="center" style="background-color:#ffffff;">
      <table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="max-width:480px;background-color:#ffffff;">
        <tr>
          <td style="padding:16px;font-family:Arial,sans-serif;font-size:16px;line-height:24px;color:#1a1a1a;background-color:#ffffff;">
            Hi {{ ${first_name} | default: 'there' }}, your order is on its way.
          </td>
        </tr>
      </table>
    </td>
  </tr>
</table>

‍

The outer table fills the screen and carries the page colour. The inner table holds the readable column, and each cell repeats its background colour so a dark theme has nothing to guess.

‍

Where does this connect to the rest of the programme?

Layout is one part of a working email. Our guide to high-converting email campaigns covers content and calls to action, and email deliverability setup covers getting to the inbox at all.

Reusable blocks are covered in seven ways to deliver dynamic content. Testing layout variants against each other is in A/B testing your email campaigns, and measuring the result is in email campaign reporting.

As a Braze implementation partner, CustomerIK recommends deleting the style block from a draft template and reading what's left. If that version works on a phone, the template is ready for the media queries.

‍

Frequently Asked Questions
‍

1. Can I preview dark mode in the Braze drag-and-drop editor?

Yes. Go to Preview and Test in the drag-and-drop editor and turn on Dark mode, then confirm in Inbox Vision across clients.

2. Can I set different padding for mobile in the drag-and-drop editor?

Not separately, because padding edits apply to both views. The HTML editor lets you add CSS that sets padding by screen size.

3. Why does my email show the desktop layout in the Gmail app?

Gmail may remove the whole style block if the email has too much CSS or CSS it doesn't support. Build a layout that reads well without the style block.

4. How wide should a responsive email template be?

Braze advises keeping the width under 500 pixels if one template serves both mobile and desktop.

5. Does Braze inline CSS in Connected Content responses?

It doesn't. Inlining runs before Connected Content is evaluated, so return HTML with its styles already inline.

‍

Sources

• Braze, Drag-and-drop editor. Retrieved 14 Oct 2026.
• Braze, Drag-and-drop editor FAQ. Retrieved 14 Oct 2026.
• Braze, Email guidelines. Retrieved 14 Oct 2026.
• Braze, CSS inlining. Retrieved 14 Oct 2026.
• Braze, Inbox Vision. Retrieved 14 Oct 2026.
• Braze, Email global style settings. Retrieved 14 Oct 2026.
• Braze, Liquid frequently asked questions. Retrieved 14 Oct 2026.

‍

CustomerIK is a Braze implementation partner working across onboarding, technical integration, marketing operations and customer data management.

If you're rebuilding your email templates and want a second pair of eyes on the mobile layout, let's talk.

‍