Email Template Implementation Manual

This document defines the standards and best practices for creating consistent, reliable, and cross-client–compatible HTML email templates.
Following these guidelines ensures that emails render correctly across major clients such as Outlook, Gmail, Apple Mail, and mobile devices.

For the information on how to edit and implement already built templates in Unidy, please refer to the docs.

1. Layout

Always use <table> elements for structure

• Do not use <div> for layout — Outlook does not support modern CSS layout systems (e.g., flexbox, grid).

• Use fixed attributes for all table elements:

  <table width="600" align="center" cellpadding="0" cellspacing="0" border="0">
  

• For multiple columns, nest tables inside each other rather than using CSS positioning.

Example:

<table width="600" cellpadding="0" cellspacing="0" border="0" align="center">
  <tr>
    <td width="300">Column 1</td>
    <td width="300">Column 2</td>
  </tr>
</table>

2. Styling

All CSS must be written inline

• Apply styles directly in the HTML element:

  <td style="font-size:16px; line-height:24px;">Text content</td>
  

• Avoid CSS shorthand notation.
  Instead of:

  margin: 10px 0;
  

  use:

  margin-top:10px; margin-bottom:10px;
  

• Do not use unsupported properties like:

  • float

  • flexbox

  • position

  These are ignored by Outlook.

3. Images

Always include explicit size and description attributes

• Every image must include:

  <img src="https://example.com/image.jpg" width="200" height="100" alt="Description" />
  

• Use absolute URLs (https://...), never relative paths.

• Do not use background images, unless you implement a VML fallback for Outlook.

4. Buttons (CTAs)

Create buttons using tables with inline styles

• Buttons should be table-based, not <button> or <a> styled with block properties.

• Always include an Outlook VML fallback to ensure the button renders correctly in Outlook clients.

Example (Optimized for Outlook):

<tr>
  <td width="100%" align="center">
    <table class="sub-container" width="600" align="center" border="0" cellpadding="0" cellspacing="0">
      <tr>
        <td align="center" valign="top">
          <!--[if mso]>
          <v:roundrect xmlns:v="urn:schemas-microsoft-com:vml"
            href="<%= accept_invitation_url(@resource, invitation_token: @token) %>"
            style="height:47px;v-text-anchor:middle;width:260px;" arcsize="10%" stroke="f" fillcolor="#ffffff">
            <w:anchorlock/>
            <center style="color:#070707;font-family:Arial,sans-serif;font-size:16px;font-weight:700;">
              Créer mon mot de passe
            </center>
          </v:roundrect>
          <![endif]-->
          <!--[if !mso]><!-->
          <table width="auto" border="0" cellspacing="0" cellpadding="0" align="center">
            <tr>
              <td align="center" valign="middle" height="47"
                style="font-family:Helvetica,Arial,sans-serif;font-size:16px;color:#070707;font-weight:400;height:47px;width:260px;background:#ffffff;border-radius:5px;">
                <a href="<%= accept_invitation_url(@resource, invitation_token: @token) %>"
                  style="color:#070707;text-decoration:none;display:block;font-weight:600;"
                  target="_blank">Créer mon mot de passe</a>
              </td>
            </tr>
          </table>
          <!--<![endif]-->
        </td>
      </tr>
    </table>
  </td>
</tr>

5. Fonts & Text

Use only web-safe fonts

• Recommended fonts:
  Arial, Helvetica, Georgia, Times New Roman

• Always define a fallback font (e.g., font-family: Arial, Helvetica, sans-serif;)

• Set line-height inline to control spacing:

  <td style="font-size:16px; line-height:24px;">Your text here</td>
  

6. Spacing

Use padding for spacing inside <td>

• Example:

  <td style="padding:20px 0;">Content</td>
  

• Avoid margin — it is inconsistently supported in Outlook.

• For vertical spacing, insert a spacer row:

  <tr><td height="20">&nbsp;</td></tr>
  

7. Responsive Design

Mobile optimization guidelines

• Use percentage-based widths for mobile layouts:

  <table width="100%" style="max-width:600px;">
  

• max-width media queries work in Gmail and Apple Mail, but not in Outlook.

• Always provide a desktop fallback version.

8. Testing

Always test before sending

• Test in major clients:

  • Outlook (Windows, Mac)

  • Gmail (Web & Mobile)

  • Apple Mail

• Use professional tools for validation:

  • Litmus

  • Email on Acid

• Verify that:

  • Buttons display correctly in Outlook.

  • Links function as expected.

  • Layouts remain intact on both desktop and mobile.

When new templates are implemented and ready for testing, they are first implemented on the staging environment for validation before going live on production.