Introduction

Writing Outlook conditionals in HTML emails is gross:

``html

`

It gets even worse when you need to target _specific versions_:

`html

`

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

`xml





`

Like, really simple:

`xml





`

Install

`
npm i posthtml-mso
`

Usage

`js
import posthtml from 'posthtml'
import mso from 'posthtml-mso'

const options = { / see options below / }

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

//
`

Syntax

The plugin provides two (customizable) tags:

1.
2.

$3

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:

`xml





`

Result:

`html

`

$3

This tag will basically hide content from all Outlook versions:

`xml





`

Result:

`html





`

$3

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_)

$3

Show the content only in this Outlook version:

`xml





`

Result:

`html

`

It also supports multiple, comma-separated versions:

`xml





`

Result:

`html

`

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

$3

Show content in all Outlook versions except the ones specified.

`xml





`

Result:

`html

`

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

`xml





`

Result:

`html

`

$3

Show in all versions before this one, excluding it:

`xml





`

Result:

`html

`

$3

Show in all versions before this one, including it:

`xml





`

Result:

`html

`

$3

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

`xml





`

Result:

`html

`

$3

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

`xml





`

Result:

`html

`

Combining Attributes

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

`xml





`

Result:

`html

`

Gotchas

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

$3

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.

$3

Consider this example:

`xml





`

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

The result will be:

`html

`

$3

Made a typo like this?

`xml





`

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

`html



`

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

Options

$3

Type: string\
Default: outlook

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

For example:

`js
import posthtml from 'posthtml'
import mso from 'posthtml-mso'

const html =
Show in Outlook 2013
Hide from Outlook

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

//
// Hide from Outlook
``

[npm]: https://www.npmjs.com/package/posthtml-mso
[npm-version-shield]: https://img.shields.io/npm/v/posthtml-mso.svg
[npm-stats]: http://npm-stat.com/charts.html?package=posthtml-mso
[npm-stats-shield]: https://img.shields.io/npm/dt/posthtml-mso.svg
[github-ci]: https://github.com/posthtml/posthtml-mso/actions
[github-ci-shield]: https://github.com/posthtml/posthtml-mso/actions/workflows/nodejs.yml/badge.svg
[license]: ./license
[license-shield]: https://img.shields.io/npm/l/posthtml-mso.svg