Why Merge Fields Break Mobile Layout in Altru Emails (and How to Fix It)

The test email looked fine on your desktop. Then someone opened the real send on a phone and the whole message was wider than the screen: tiny text, sideways scrolling, a button hanging off the right edge. Take the merge fields out and the template behaves. Put them back and it breaks again.

That pattern is common, and it almost never means the merge field itself is “broken.” It means the value Altru drops into that spot, or the markup that came along with the field when it was inserted, is forcing the layout wider than a phone can show. Below are the usual causes, how to tell which one you have, and the fixes that hold up.

The four usual causes

1. A long value with nowhere to wrap

Browsers and email apps wrap text at spaces. A merge field that produces one long unbroken string, such as an email address, a full URL, a long lookup ID or a household name joined with no spaces, can’t wrap. On a narrow screen that string pushes its container wider, and in a table-based email the whole table stretches to match. Your test record probably had a short value. The member with a 40-character work email address is the one whose copy breaks.

2. Hidden formatting that came in with the field

When a field is inserted into text that was pasted from Word, Outlook or another web page, the editor can wrap it in extra <span> or <div> tags carrying fixed widths, white-space: nowrap, or desktop font sizes. You can’t see any of that in the design view. It only shows up when the email is squeezed onto a small screen.

3. The field sits inside a fixed-width table

Many email templates are built from tables with hard-coded pixel widths (600px is typical). A static template can get away with that because the content never changes. Add a merge field in a side-by-side column or a cell with a fixed width, and any value longer than you planned for forces the table out of shape. Two-column layouts with names or addresses in one column are the usual culprit.

4. Responsive CSS that the email app ignores

If your template relies on a <style> block with media queries to collapse columns on phones, some email apps strip or partly ignore it. The layout then falls back to its desktop widths, and merge field content makes the problem visible. This one isn’t strictly caused by the field, but it often gets blamed on it.

Finding which one you have

1. Send tests to real records, not your own. Pick constituents with the longest names, longest email addresses and longest values for whatever fields you use. Queries make it easy to find them. Open each test on an actual phone, ideally on both an iPhone and an Android device, since their mail apps render differently.
2. Swap the field for plain text of the same length. If a typed 40-character string breaks the layout the same way, the cause is length and wrapping, not the field.
3. Look at the HTML around the field. If your editor lets you view source, check what wraps the merge field. Fixed widths, nowrap, or a pile of nested spans and font tags point to cause 2. If you can’t see the source in your version of the Altru editor, Blackbaud support can confirm how fields are inserted and what markup is kept.
4. Check the table widths. Find the table or cell that contains the field and note any pixel widths on it or its parents.

Fixes that hold up

• Let long strings wrap. On the cell or paragraph that holds the field, add inline word-break: break-word; and overflow-wrap: anywhere;. Inline styles survive more email apps than a <style> block does. Not every client honors them, so test after the change.
• Don’t print raw URLs. If a merge field produces a link, put it behind short link text (“View your tickets”) rather than showing the whole address.
• Clean up pasted content. Delete the paragraph that holds the field, retype it as plain text in the editor, then insert the field again. If your editor has a “paste as plain text” option, use it for anything copied from Word or another email.
• Use fluid widths. Replace fixed pixel widths with width: 100% plus a max-width (for example, 600px) on the outer container. Avoid placing variable-length fields in narrow side-by-side columns. Stacking content in a single column is the most reliable option for phones.
• Build for the worst value. Decide the longest realistic value for each field and design for it. If a field can be blank for some records, check that the empty state doesn’t leave a broken line or an orphaned label.

When it keeps coming back

If every new template means another round of hand-editing HTML, the problem is usually the starting template, not the fields. Rebuild one clean, single-column, fluid-width base template, test it on phones with your longest records, and copy it for each new email instead of starting from an old desktop design. It takes an afternoon and stops most of the repeat cases.

Some teams decide they’d rather not maintain email HTML at all. Social Good’s Email Designer sends automated, branded emails such as eTickets, acknowledgments and renewal notices straight from Altru queries without manual exports. It’s one option if template upkeep is eating staff time. Either way, the checks above are worth doing first, since they’ll tell you whether you’re dealing with one bad template or a pattern.

Quick answers

Why does the email look fine in the preview but not on my phone?
Previews usually render at desktop width and often with sample or short data. The phone shows the real value at a narrow width, which is where wrapping and fixed-width problems appear.

Will removing the field fix it?
Sometimes, but you lose the personalization. It’s better to find out whether the cause is length, hidden markup or table widths, and fix that.