Outlook and MSO rendering

What the Word rendering engine ignores, and what to use instead

June 25, 2026

No fixed retirement date. The issues on this page are specific to classic Outlook's Word rendering engine, which is not being replaced or patched. Microsoft is pushing a separate, browser-based new Outlook as the default starting April 2026, but classic Outlook, Word engine included, stays supported until at least 2029, with no cutover date announced beyond that. Why the October 2026 date you may have seen is wrong

The problem

Classic Outlook - the Windows desktop app - renders email using the Microsoft Word rendering engine, not a browser engine.

Despite what a lot of email-dev blogs still say, there's no confirmed retirement date for it: Microsoft has only committed to a new-Outlook default switch in April 2026, and classic Outlook (Word engine included) stays supported for existing installs until at least 2029, with no cutover date announced beyond that. See the full timeline breakdown.

The engine itself has barely changed since 2007 - two minor updates in nearly two decades (a cosmetic 2007 standards push, and max-width support added via a 2016 Litmus partnership). Treat everything on this page as a fixture, not a countdown.

The Word engine implements only the subset of CSS that Word itself needs for document layout. Everything else - rounded corners, CSS background images, flexbox, dark mode media queries - is silently ignored. Your email doesn't throw an error. It just renders without those properties, often in ways that completely break the design.

Outlook still accounts for a significant share of corporate email clients, particularly in enterprise environments. If you're sending transactional email to business users, you're sending to Outlook users.

Why it's hard

The difficulty isn't just knowing which CSS properties fail - it's that you need to write two rendering paths in one HTML file. One path for Outlook (using HTML attributes, table-based layout, and occasionally VML - a vector graphics format from 1999), and one path for everyone else (using CSS).

Microsoft added a proprietary mechanism for this: MSO conditional comments. These are HTML comments that Outlook's parser reads as conditional blocks. Every other client treats them as comments and ignores the content inside. This lets you serve fundamentally different HTML to Outlook without breaking modern clients.

The manual solution

MSO conditional comments

The basic pattern for serving different HTML to Outlook vs. everyone else:

<!-- This HTML is only shown in Outlook (mso = Microsoft Office) -->
<!--[if mso]>
<table role="presentation" width="600">
  <tr><td>Outlook-specific content here</td></tr>
</table>
<![endif]-->

<!-- This HTML is hidden from Outlook, shown to everyone else -->
<!--[if !mso]><!-->
<div style="max-width:600px; margin:0 auto;">
  Modern client content here
</div>
<!--<![endif]-->

What works vs. what doesn't

These CSS properties render correctly in classic Outlook:

/* These CSS properties work reliably in classic Outlook */
font-family: sans-serif;         /* Outlook will substitute the closest system font */
font-size: 16px;
font-weight: bold;
color: #333333;
background-color: #f5f5f5;       /* Solid colors only, no gradients */
padding: 16px;                   /* On <td> elements, not on divs */
margin: 0;
width: 600px;                    /* On <table> and <td> with matching HTML attribute */
text-align: left;
vertical-align: top;
border: 1px solid #cccccc;       /* Simple borders work */
line-height: 1.5;

These are silently ignored:

/* These CSS properties are IGNORED in classic Outlook */
border-radius: 6px;              /* No rounded corners: use VML for buttons */
background-image: url(...);      /* No CSS backgrounds: use VML */
background: linear-gradient(...);/* No gradients at all */
display: flex;                   /* No flexbox */
display: grid;                   /* No grid */
max-width: 600px;                /* Ignored: use width attribute on <table> */
box-shadow: ...;                 /* Ignored */
transform: ...;                  /* Ignored */
@media (prefers-color-scheme: dark) { ... }  /* Media queries are stripped */

Border-radius: accept square corners in Outlook

For most elements, the right call is to accept that Outlook users see square corners. Buttons are the exception, and the VML roundrect pattern under Buttons and CTAs below covers them. For cards, images, and divs, don't fight it:

<!-- Border-radius doesn't exist in Outlook.
     Use a solid background color rectangle with a VML shape for the button,
     and accept that Outlook users see a square-cornered button.
     The VML pattern below is the fallback when you can't. -->

<!-- Works everywhere except Outlook (square corners in Outlook): -->
<a href="https://example.com"
   style="display:inline-block;
          padding:12px 24px;
          background:#6e7ef0;
          color:#ffffff;
          border-radius:6px;
          text-decoration:none;
          font-family:sans-serif;">
  Click here
</a>

Background images: VML is the only option

If you need a full-bleed image behind content in Outlook, VML is the only path. It's verbose and arcane, but it works:

<!-- This background image WILL NOT show in Outlook -->
<div style="background-image:url('hero.jpg'); padding:40px;">
  Content on top of image
</div>

<!-- Outlook requires VML for background images -->
<!--[if mso]>
<v:rect xmlns:v="urn:schemas-microsoft-com:vml"
        style="width:600px; height:200px;" stroked="false">
  <v:fill type="frame" src="hero.jpg" />
  <v:textbox inset="20px,20px,20px,20px">
<![endif]-->
    <div style="padding:40px;">
      Content on top of image
    </div>
<!--[if mso]>
  </v:textbox>
</v:rect>
<![endif]-->

Buttons and CTAs

A styled <a> tag looks correct in Gmail and Apple Mail. In classic Outlook the same element renders as unstyled underlined text: background color, border-radius, and padding all fall through. This is what most tutorials show:

<!-- Looks good in Gmail, Apple Mail, Outlook.com -->
<!-- Renders as plain unstyled text in classic Outlook -->
<a href="https://example.com"
   style="display:inline-block;
          padding:12px 24px;
          background:#6e7ef0;
          color:#ffffff;
          border-radius:6px;
          text-decoration:none;
          font-family:Arial,sans-serif;
          font-size:16px;
          font-weight:bold;">
  Confirm your email
</a>

The fix is a VML v:roundrect shape wrapped in MSO conditional comments. Outlook renders the VML; every other client renders the plain CSS link. The mso-hide:all on the <a> prevents Outlook from rendering both:

<!--[if mso]>
<v:roundrect xmlns:v="urn:schemas-microsoft-com:vml"
             xmlns:w="urn:schemas-microsoft-com:office:word"
             href="https://example.com"
             style="height:44px; width:200px; v-text-anchor:middle;"
             arcsize="15%"
             strokecolor="#5a68d4"
             fillcolor="#6e7ef0">
  <w:anchorlock/>
  <center style="color:#ffffff;
                 font-family:Arial,sans-serif;
                 font-size:16px;
                 font-weight:bold;">
    Confirm your email
  </center>
</v:roundrect>
<![endif]-->
<!--[if !mso]><!-->
<a href="https://example.com"
   style="display:inline-block;
          padding:12px 24px;
          background:#6e7ef0;
          color:#ffffff;
          border-radius:6px;
          text-decoration:none;
          font-family:Arial,sans-serif;
          font-size:16px;
          font-weight:bold;
          mso-hide:all;">
  Confirm your email
</a>
<!--<![endif]-->

VML shapes don't respond to text-align from a parent. To center a button, wrap the whole pattern in a table cell with align="center":

<!-- Centering a button in both Outlook and modern clients -->
<table role="presentation" width="100%" cellpadding="0" cellspacing="0">
  <tr>
    <td align="center" style="padding:24px 0;">
      <!--[if mso]>
      <v:roundrect xmlns:v="urn:schemas-microsoft-com:vml"
                   xmlns:w="urn:schemas-microsoft-com:office:word"
                   href="https://example.com"
                   style="height:44px; width:200px; v-text-anchor:middle;"
                   arcsize="15%"
                   strokecolor="#5a68d4"
                   fillcolor="#6e7ef0">
        <w:anchorlock/>
        <center style="color:#ffffff;
                       font-family:Arial,sans-serif;
                       font-size:16px;
                       font-weight:bold;">
          Get started
        </center>
      </v:roundrect>
      <![endif]-->
      <!--[if !mso]><!-->
      <a href="https://example.com"
         style="display:inline-block;
                padding:12px 24px;
                background:#6e7ef0;
                color:#ffffff;
                border-radius:6px;
                text-decoration:none;
                font-family:Arial,sans-serif;
                font-size:16px;
                font-weight:bold;
                mso-hide:all;">
        Get started
      </a>
      <!--<![endif]-->
    </td>
  </tr>
</table>

Gotchas to watch for

Outlook.com is different from classic Outlook. Outlook.com (the web client) renders with a real browser engine and behaves like Gmail or Apple Mail. MSO conditional comments don't fire there. The Word engine issues are specific to the desktop app. Outlook.com's dark mode rewrites contrast-failing colors and stores the originals in [data-ogsc] attributes, which you can target with attribute selectors if you need to undo the rewrite.
Outlook mobile also differs. Outlook for Android and iOS render with a browser-based engine, not Word, so they aren't subject to the desktop-specific limitations on this page.
Width attributes must match CSS widths. For tables and cells, set the width in both the HTML width attribute and the style attribute. Outlook uses the HTML attribute; other clients use the CSS. If they don't match, one group gets the wrong layout.
Padding on divs is unreliable. In the Word engine, padding on <div> elements is inconsistent. Apply padding to <td> elements instead.
Dark mode media queries are stripped entirely. Outlook's Word renderer removes @media (prefers-color-scheme: dark) from the <style> block before rendering. There's no CSS-only workaround - correct Outlook dark mode requires a separate VML/MSO code path.
New Outlook is a different app, not an update. "New Outlook for Windows" is a separate, browser-engine application Microsoft ships alongside classic Outlook, not a patch to it. A recipient can be on either one, and only classic Outlook has the Word-engine issues this page describes. If a customer reports a rendering bug, ask which Outlook they're running before assuming the VML/MSO fixes apply.

Sources

How Postcraft handles this

Postcraft's email render target generates MSO-safe HTML automatically. Table structure, VML button fallbacks, and conditional comments are all handled for you. You design once; the API handles the Word engine translation.

Try it free

All topics