Outlook HTML Email: MSO Conditional Comments and mso- CSS

Why Outlook needs its own code

Outlook Classic on Windows renders email with Microsoft Word, while Outlook on the web, on a Mac and the new Outlook for Windows use browser engines. Which Outlook uses which engine, and what Word does with each CSS property, is in the Outlook CSS support guide. This page is the tools for writing markup Word alone will read.

MSO conditional comments: markup only Outlook reads

Outlook respects Microsoft's old conditional-comment syntax. Anything between <!--[if mso]> and <![endif]--> is read by Outlook Classic ("mso" stands for Microsoft Office) and treated as an ordinary HTML comment by every other client, the new Outlook included.

<!--[if mso]>
  <table role="presentation" width="600"><tr><td>
<![endif]-->
  ...content every client sees...
<!--[if mso]>
  </td></tr></table>
<![endif]-->

Here the comment hands Outlook a fixed 600px table around content everyone sees. The condition can also compare versions, as in <!--[if gte mso 9]> (gte: greater than or equal), the form the VML snippets in the background-image and gradient guides open with.

Hiding content from Outlook with [if !mso]

The reverse, markup every client renders except Outlook Classic, needs a slightly odd form. <!--[if !mso]><!--> opens a condition for Outlook and closes the comment straight away for everyone else, so other clients render what follows; <!--<![endif]--> ends it. Put the two blocks side by side and each client gets exactly one version:

<!--[if mso]>
  ...markup for Outlook Classic only...
<![endif]-->

<!--[if !mso]><!-->
  ...markup for every other client...
<!--<![endif]-->

This is how a rounded button ships a VML <v:roundrect> to Outlook and a CSS link to everyone else; the full button is in border-radius in Outlook.

Where conditional comments go in an Outlook template

• In the head. Word's document settings, inside a conditional comment. The <o:PixelsPerInch>96</o:PixelsPerInch> line keeps Word on a 96 DPI baseline, so VML shapes do not grow when Windows display scaling is set to 125% or 150%.
• On the html tag. The VML and Word namespaces, xmlns:v="urn:schemas-microsoft-com:vml" and xmlns:w="urn:schemas-microsoft-com:office:word", if the email uses VML.
• Around columns. A fixed-width table for Outlook around inline-block columns: Outlook ghost tables.
• Around VML. Rounded buttons and gradients (Outlook CSS fallbacks) and background images (background images in Outlook).

<!-- Inside the <head> of the email -->
<!--[if mso]>
<xml>
  <o:OfficeDocumentSettings>
    <o:AllowPNG/>
    <o:PixelsPerInch>96</o:PixelsPerInch>
  </o:OfficeDocumentSettings>
</xml>
<![endif]-->

mso- CSS properties for Outlook

Word reads a set of proprietary CSS properties that other clients ignore. They fix spacing that Word gets wrong:

Put mso-table-lspace: 0pt; mso-table-rspace: 0pt; on every layout table, next to border-collapse: collapse; together they are part of the fix for Outlook's thin lines across table columns, described in Outlook CSS fallbacks.

Build the layout with tables

For Word-based Outlook, tables are the only reliable layout mechanism: every row, column and content block is a <table>, <tr> and <td>. MJML and React Email compile to tables for you; the Outlook CSS support guide shows both.