posthtml/posthtml-mso

Makes writing Outlook conditionals in HTML emails easy.

Outlook Conditionals

Makes it easy to write Outlook conditionals in HTML emails

Introduction

Writing Outlook conditionals in HTML emails is gross:

<!--[if mso]>
  <div>Show this in all Outlook versions</div>
<![endif]-->

It gets even worse when you need to target specific versions:

<!--[if (gt mso 11)&(lte mso 15)]>
  <div>Show in 2007, 2010, 2013</div>
<![endif]-->

This PostHTML plugin simplifies the way you write Outlook conditional comments:

<outlook>
  <div>Show this in all Outlook versions</div>
</outlook>

Like, really simple:

<outlook gt="2003" lte="2013">
  <div>Show in 2007, 2010, 2013</div>
</outlook>

Install

npm i posthtml-mso

Usage

import posthtml from 'posthtml'
import mso from 'posthtml-mso'

const options = { /* see options below */ }

posthtml([mso(options)])
  .process('<outlook only="2013">Show in Outlook 2013</outlook>')
  .then(result => console.log(result.html))

  // <!--[if mso 15]>Show in Outlook 2013<![endif]-->

Syntax

The plugin provides two (customizable) tags:

1. <outlook>
2. <not-outlook>

<outlook>

This will output the content inside it, wrapped in an Outlook conditional comment.

The conditional is created based on the Outlook version(s) you need to target, which you can define inside special attributes (documented below).

Using the tag with no attributes will target all Outlook versions:

<outlook>
  <div>Show this in all Outlook versions</div>
</outlook>

Result:

<!--[if mso]>
  <div>Show this in all Outlook versions</div>
<![endif]-->

<not-outlook>

This tag will basically hide content from all Outlook versions:

<not-outlook>
  <div>All Outlooks will ignore this</div>
</not-outlook>

Result:

<!--[if !mso]><!-->
  <div>All Outlooks will ignore this</div>
<!--<![endif]-->

Attributes

To define which Outlook versions you are targeting, you can use one of the following attributes:

• only - show only in these Outlook versions
• not - show in all versions except these
• lt - all versions before this (not including it, i.e. lower than)
• lte - all versions before this (including it, i.e. lower than or equal to)
• gt - all versions after this (not including it, i.e. greater than)
• gte - all versions after this (including it, i.e. greater than or equal to)

only

Show the content only in this Outlook version:

<outlook only="2013">
  <div>Show only in Outlook 2013</div>
</outlook>

Result:

<!--[if mso 15]>
  <div>Show only in Outlook 2013</div>
<![endif]-->

It also supports multiple, comma-separated versions:

<outlook only="2013,2016">
  <div>Show only in Outlook 2013 and 2016</div>
</outlook>

Result:

<!--[if (mso 15)|(mso 16)]>
  <div>Show only in Outlook 2013 and 2016</div>
<![endif]-->

Note: targeting Outlook 2016 will also target Outlook 2019 (see gotchas).

not

Show content in all Outlook versions except the ones specified.

<outlook not="2013">
  <div>Don't show in Outlook 2013</div>
</outlook>

Result:

<!--[if !mso 15]>
  <div>Don't show in Outlook 2013</div>
<![endif]-->

You can also specify a comma-separated list of versions:

<outlook not="2013,2016">
  <div>Don't show in Outlook 2013 and 2016</div>
</outlook>

Result:

<!--[if !((mso 15)|(mso 16))]>
  <div>Don't show in Outlook 2013 and 2016</div>
<![endif]-->

lt

Show in all versions before this one, excluding it:

<outlook lt="2007">
  <div>Show in all Outlooks before 2007, excluding it</div>
</outlook>

Result:

<!--[if lt mso 12]>
  <div>Show in all Outlooks before 2007, excluding it</div>
<![endif]-->

lte

Show in all versions before this one, including it:

<outlook lte="2007">
  <div>Show in all Outlooks before 2007, including it</div>
</outlook>

Result:

<!--[if lte mso 12]>
  <div>Show in all Outlooks before 2007, including it</div>
<![endif]-->

gt

Show in all Outlook versions after this one, excluding it:

<outlook gt="2007">
  <div>Show in Outlook 2010, 2013, 2016, 2019</div>
</outlook>

Result:

<!--[if gt mso 12]>
  <div>Show in Outlook 2010, 2013, 2016, 2019</div>
<![endif]-->

gte

Show in all Outlook versions after this one, excluding it:

<outlook gte="2007">
  <div>Show in Outlook 2007, 2010, 2013, 2016, 2019</div>
</outlook>

Result:

<!--[if gte mso 12]>
  <div>Show in Outlook 2007, 2010, 2013, 2016, 2019</div>
<![endif]-->

Combining Attributes

You can combine the lt, gt, lte, and gte attributes if you need to target multiple versions with higher accuracy.

<outlook gt="2003" lte="2013">
  <div>Show in 2007, 2010, 2013</div>
</outlook>

Result:

<!--[if (gt mso 11)&(lte mso 15)]>
  <div>Show in 2007, 2010, 2013</div>
<![endif]-->

Gotchas

There are some cases that might not work as you'd expect.

Outlook 2019

Outlook 2019 uses the same version identifier as Outlook 2016 - 16.

Because of this, if you target either of them you will be targeting them both. Currently there is no way around this.

Duplicate Attributes

Consider this example:

<outlook gt="2003" lte="2013" gt="2007">
  <div>Show in 2007, 2010, 2013</div>
</outlook>

Since duplicate attributes are discarded when parsing, gt="2007" will not be taken into consideration.

The result will be:

<!--[if (gt mso 11)&(lte mso 15)]>
  <div>Show in 2007, 2010, 2013</div>
<![endif]-->

Unknown Versions

Made a typo like this?

<outlook lt="20007">
  <div>Target Outlooks before 2007</div>
</outlook>

If an unknown Outlook version is specified, the plugin will skip the tag and return its contents:

<div>Target Outlooks before 2007</div>

Hopefully, we won't need this plugin by then...

Options

tag

Type: string
Default: outlook

The name of the tag you want the plugin to use. Will be used for both available tags.

For example:

import posthtml from 'posthtml'
import mso from 'posthtml-mso'

const html = `
  <mso only="2013">Show in Outlook 2013</mso>
  <not-mso>Hide from Outlook</not-mso>
`

posthtml([mso({ tag: 'mso' })])
  .process(html)
  .then(result => console.log(result.html))

  // <!--[if mso 15]>Show in Outlook 2013<![endif]-->
  // <!--[if !mso]><!-->Hide from Outlook<!--<![endif]-->