Troubleshooting Common Email Client Formatting Issues

Email clients (especially Microsoft Outlook for Windows and Gmail) use divergent, legacy rendering engines. Microsoft Outlook on Windows relies on Microsoft Word's layout engine (MSO), while Gmail alters image margins and strips embedded <style> blocks.

This document details proven technical resolutions for common cross-client rendering bugs in TeamSigs templates.

1. Resolving Image Spacing Gaps in Gmail

The Symptom

Images (such as logos, profile avatars, or social icons) render with an unwanted 3px to 5px blank margin along their bottom edge in Gmail Web and Gmail Mobile apps.

Root Cause

Gmail treats HTML <img> elements as inline elements by default (display: inline). The browser reserves vertical space beneath the image baseline for descenders (the tail of characters like g, y, p, and j).

The Solution

1. Enforce block display on all images: Add display: block; to the inline style of every <img> element:

   <!-- Incorrect -->
   <img src="{{company_logo_url*}}" 
        width="120" height="40" alt="Logo" />
   
   <!-- Correct -->
   <img src="{{company_logo_url*}}" 
        width="120" 
        height="40" 
        alt="Logo" 
        style="display:block;border:0;outline:none;" />

2. Reset parent table cell font metrics: When an image sits inside a table cell (<td>), reset the font size and line height on the parent container:

   <td style="font-size:0;line-height:0;padding:0;">
     <img src="{{company_logo_url*}}" 
          width="120" 
          height="40" 
          style="display:block;border:0;" />
   </td>

3. Avoid whitespace between HTML tags: Do not leave line breaks or indentation spaces between the closing <td> and the <img> tag:

   <!-- Incorrect (whitespace creates inline text nodes) -->
   <td>
     <img src="{{company_logo_url*}}" />
   </td>
   
   <!-- Correct -->
   <td style="line-height:0;font-size:0;"><img 
     src="{{company_logo_url*}}" 
     width="120" 
     style="display:block;border:0;" /></td>

2. Fixing Line Breaks & Scaling Issues in Microsoft Outlook (Desktop)

The Symptom

Signatures look balanced in the web preview, but when opened in Outlook for Windows (2016, 2019, 2021, and Office 365 desktop):

• Content drops down to a new row unexpectedly.
• Table borders collapse or expand uncontrollably.
• Spacing balloons when Windows displays scale to 125% or 150% DPI.

Root Cause

Outlook desktop renders HTML using the Microsoft Word rendering engine (MSO). Word does not support div float layouts, CSS flexbox, CSS grid, max-width, or standard CSS box-sizing. Word also miscalculates table cell widths when column widths are not explicitly set at both the table and cell level.

Solutions

A. Enforce Explicit Table Widths and Cell Resets

Always set table widths using both HTML attributes and inline CSS styles:

<!-- Incorrect -->
<table style="width:100%;max-width:500px;">

<!-- Correct -->
<table cellpadding="0" 
       cellspacing="0" 
       border="0" 
       width="480" 
       style="width:480px;border-collapse:collapse;
              mso-table-lspace:0pt;
              mso-table-rspace:0pt;">
  <tr>
    <td width="140" 
        style="width:140px;vertical-align:top;">
      <!-- Column 1 -->
    </td>
    <td width="340" 
        style="width:340px;vertical-align:top;">
      <!-- Column 2 -->
    </td>
  </tr>
</table>

B. Force Exact Line Heights for MSO

Outlook can inflate line-height across text blocks. Add mso-line-height-rule: exactly; to every paragraph, span, or table cell where font size is defined:

<p style="margin:0;font-size:13px;line-height:16px;
          mso-line-height-rule:exactly;color:#334155;">
  {{job_title}}
</p>

C. Prevent HiDPI Image Blowout

When an employee uses a high-resolution 4K monitor set to 150% scaling, Outlook for Windows will upscale images based on their physical pixel count rather than CSS rules.

To guarantee retina quality without image distortion:

1. Save your source graphic at 2x physical dimensions (e.g., upload a 240px wide logo).
2. Set the physical display width using the HTML width attribute at 1x (e.g., width="120").
3. Specify the CSS width in inline styles:

   <img src="{{company_logo_url*}}" 
        width="120" 
        height="40" 
        style="display:block;width:120px;
               height:40px;border:0;" />

3. Troubleshooting Missing or Blank Fields in Conditional Wrappers

The Symptom

• Entire sections of a signature disappear unexpectedly.
• Separator characters (like | or •) remain visible with no content next to them.
• Variables render raw text tags like [[if:phone]] in the recipient's email.

Root Cause Analysis & Fixes

A. Mismatched Syntax Suffixes

The opening condition tag and closing tag must match the variable suffix exactly.

<!-- INCORRECT: Mismatched Tier 3 suffix -->
[[if:booking_link#]]
  <a href="{{booking_link#}}">Schedule Call</a>
[[/if:booking_link]] <!-- Missing hash breaks parser -->

<!-- CORRECT -->
[[if:booking_link#]]
  <a href="{{booking_link#}}">Schedule Call</a>
[[/if:booking_link#]]

B. Orphaned Punctuation Outside Conditional Blocks

If a separator or label is placed outside the conditional block, it will display even when the data field is completely empty.

<!-- INCORRECT: Bullet renders if phone is missing -->
<span>{{email}}</span> · [[if:phone]]{{phone}}[[/if:phone]]

<!-- CORRECT: Delimiter is encapsulated within condition -->
<span>{{email}}</span>
[[if:phone]]
  <span style="color:#cbd5e1;">·</span> {{phone}}
[[/if:phone]]

C. Malformed Table Row Nesting

Never place conditional tags across mismatched table structures. The opening [[if:...]] and closing [[/if:...]] must wrap the complete <tr>...</tr> or <td>...</td> segment.

<!-- INCORRECT: Leaves table rows unclosed if empty -->
<tr>
  <td>Label</td>
  [[if:department]]
  <td>{{department}}</td>
</tr>
  [[/if:department]]

<!-- CORRECT: Encapsulates entire row -->
[[if:department]]
<tr>
  <td style="font-size:12px;color:#64748b;">
    Department:
  </td>
  <td style="font-size:12px;color:#0f172a;">
    {{department}}
  </td>
</tr>
[[/if:department]]

4. Pre-Flight Template Testing Checklist

Before deploying a template as the Official Default across your organization:

1. Test with Empty Fields: In the Template Editor, clear all optional fields in the Directory Fields sidebar. Verify that no empty gaps, blank table rows, or orphaned separators appear in the live canvas.
2. Test with Long Names: Enter a 35-character name and a two-line job title to verify that the table layout does not break or push logos out of alignment.
3. Send Real Client Test Messages:
   • Send an email to a Gmail inbox and verify image spacing.
   • Send an email to an Outlook Desktop client on Windows to verify table widths and line heights.
   • Send an email to Apple Mail and test both Light and Dark mode appearances.