Fixing VML and table-layout bugs in Outlook
Quick summary: Classic Outlook for Windows renders HTML email with Microsoft Word’s engine, so it ignores much modern CSS. Build layouts from nested tables, put spacing in cell padding, set widths with attributes, wrap constrained widths in an Outlook-only “ghost” table, and use VML for background images and rounded buttons. Always test in a real Outlook install.
Why Outlook is different
Classic Outlook for Windows (the desktop versions that use Word to draw messages) supports a small part of CSS. It ignores flexbox and grid, many margin and padding cases, max-width on most elements, CSS background images and border-radius. Microsoft’s newer Outlook for Windows renders more like a browser, but classic Outlook remains widely used, so email code still needs to handle both. Check current usage in your audience before dropping support.
Use conditional comments to target it
<!--[if mso]> Outlook for Windows only <![endif]--> <!--[if !mso]><!--> Everything except Outlook for Windows <!--<![endif]--> <!--[if gte mso 9]> Outlook 2000 and newer, used for VML backgrounds <![endif]-->
Common bugs and fixes
Unexpected gaps and spacing
Set cellpadding="0" cellspacing="0" border="0" on every table, add border-collapse:collapse, make images display:block with border:0, and add mso-table-lspace:0pt;mso-table-rspace:0pt. Put spacing inside td padding or in dedicated spacer rows, because padding on a div or a is often ignored.
Width and max-width ignored
Give tables and images a width attribute, not only a style. For fluid layouts that cap at 600 pixels, wrap the content in a fixed-width table that only Outlook sees:
<!--[if mso]><table role="presentation" width="600" align="center"><tr><td><![endif]--> <div style="max-width:600px;margin:0 auto;"> ...content... </div> <!--[if mso]></td></tr></table><![endif]-->
Images look huge on high-DPI screens
Add the Office document settings block in the head so Outlook renders at 96 DPI:
<!--[if mso]><noscript><xml><o:OfficeDocumentSettings> <o:PixelsPerInch>96</o:PixelsPerInch> </o:OfficeDocumentSettings></xml></noscript><![endif]-->
Declare the xmlns:v and xmlns:o namespaces on the html tag whenever you use VML or Office settings.
Line height and text size jump around
Set line-height in pixels and add mso-line-height-rule:exactly. Avoid unitless line heights in Outlook-targeted text.
Fonts fall back to Times New Roman
Outlook ignores web fonts and may drop unsupported stacks to a serif. Always end the stack with a safe font and force one for Outlook: <!--[if mso]><style>td,p,h1,h2,a{font-family:Arial,sans-serif!important;}</style><![endif]-->
Background images do not show
Use a solid bgcolor as the fallback and VML for the image. The snippet library has a tested pattern. Keep text high contrast against the fallback color in case images are blocked.
Buttons lose padding or rounded corners
Use a VML v:roundrect for Outlook and a normal link for other clients. The snippet library includes a bulletproof button, and the code studio starter template uses it.
A debugging workflow
- Start with a table skeleton that works in Outlook, then add progressive enhancements for other clients.
- Keep one change per test so you know which edit broke the layout.
- Run the markup through the code studio to catch unsupported CSS early.
- Test in real clients: classic Outlook on Windows, Outlook on the web, Gmail, and Apple Mail. Browser previews cannot reproduce Word’s rendering, and screenshot services help but do not replace a real Outlook install.
Need hands-on help with this? I freelance on email platforms, automation logic and migrations.
Ask about templates