charlie: Outlook Research

[shellscape]

Search the web for and catalog Outlook/old-IE/Word email rendering issues and their fixes. For everything you find, attempt to assert their validity in 2026. We wouldn't want to include results for rendering engines like Outlook 97 for example, as the operating system that version of outlook required is no longer used.

For example; https://www.emailonacid.com/blog/article/email-development/prevent-ie-edge-meta-tag-from-breaking-images-in-live-mail/

The most reliable sources are likely to come from github repositories like MJML and marketing blogs like the example URL above.

Please create a comprehensive comprehensive report of issues and fixes. Then create a second report analyzing jsx-email on the main branch, and make suggestions for improvements.

[charliecreates]

Report 1 — Outlook / Word / old-IE email rendering issues & fixes (2026)

What “Outlook compatibility” means in 2026 (engines)

• Classic Outlook for Windows (desktop): uses the Microsoft Word rendering engine. This is still the source of most severe HTML/CSS limitations (VML, conditional comments, limited CSS).
  Sources: https://www.litmus.com/blog/a-guide-to-rendering-differences-in-microsoft-outlook-clients , https://www.wired.com/2007/01/outlook-2007-adopts-ms-word-rendering-engine/
• New Outlook for Windows + Outlook.com (web): behaves much closer to a modern webmail client (Chromium/WebView2 class engine). Many Word-only hacks become unnecessary here, but you still need to support classic Outlook if your audience includes enterprises.
  Sources: https://www.litmus.com/blog/a-guide-to-rendering-differences-in-microsoft-outlook-clients , MJML Table Data not rendered in newer Outlook versions using WebView2 (Desktop and Android) mjmlio/mjml#2869
• Outlook for Mac: generally WebKit-like rendering (closer to Apple Mail).
  Sources: https://www.litmus.com/blog/a-guide-to-rendering-differences-in-microsoft-outlook-clients , https://9to5mac.com/2010/10/25/outlook-2011-uses-webkit-to-render-html/

What I treated as “legacy-only” in 2026

• Very old Outlook versions (pre-Word engine / e.g. Outlook 97/2000/2003): excluded from the main catalog.
• Windows Live Mail / legacy Windows Mail: mostly deprecated. I still included one commonly-circulated pitfall below as a footnote because it appears in older snippets/blog posts.

Catalog: issues → symptoms → workarounds (with 2026 validity)

Layout + modern CSS support (Word engine)

1. Modern layout CSS is unreliable/unsupported (float, position, flex, grid, etc.)

• Symptom: broken columns/stacking, ignored positioning.
• Affected: classic Outlook for Windows (Word engine).
• Fix: table-first layouts; use align + nested tables; keep CSS conservative.
• 2026 validity: still relevant if you support classic Outlook Win.
• Source: https://support.lexblog.com/hc/en-us/articles/222450227--Outlook-email-campaign-styles-reference

2. Responsive: media queries (@media) are limited (or ignored) in Outlook Win

• Symptom: “mobile styles” don’t apply; columns don’t stack.
• Affected: classic Outlook for Windows.
• Fix: use hybrid/fluid techniques where the baseline layout works without media queries; treat media queries as progressive enhancement.
• 2026 validity: still relevant for classic Outlook Win.
• Sources: https://www.litmus.com/blog/understanding-responsive-and-hybrid-email-design , https://www.caniemail.com/clients/outlook/

3. Responsive: max-width isn’t respected → use “hybrid/fluid + ghost table wrappers”

• Symptom: fluid layouts blow out on desktop Outlook; constrained containers don’t constrain.
• Affected: classic Outlook for Windows.
• Fix: for most clients, constrain with CSS; for Outlook/IE, add MSO conditional fixed-width “ghost tables” (e.g. <!--[if (gte mso 9)|(IE)]>...<![endif]-->).
• 2026 validity: still relevant; this remains the common baseline in frameworks like MJML.
• Sources: https://www.litmus.com/blog/understanding-responsive-and-hybrid-email-design , https://pkg.go.dev/github.com/preslavrachev/gomjml/mjml/html

4. Unexpected table gutters (mso-table-lspace / mso-table-rspace)

• Symptom: mysterious left/right spacing around aligned tables.
• Affected: classic Outlook for Windows.
• Fix: add mso-table-lspace:0pt; mso-table-rspace:0pt; (usually on tables and/or td).
• 2026 validity: still relevant.
• Source: https://www.goodemailcode.com/email-enhancements/mso-styles.html

Backgrounds + shapes

5. CSS background images don’t render in Word-engine Outlook

• Symptom: missing hero/background images; only background-color shows.
• Affected: classic Outlook for Windows.
• Fix: use VML <v:rect> + <v:fill> + <v:textbox> inside an MSO conditional; always include a solid background-color fallback.
• 2026 validity: still relevant.
• Sources: https://www.litmus.com/blog/the-ultimate-guide-to-background-images-in-email , Remove background support for mj-section for Outlook 16/Windows 10 mjmlio/mjml#467

6. Background cover/contain/position requires VML fill attributes

• Symptom: tiling/misalignment; background-size ignored.
• Affected: classic Outlook for Windows.
• Fix: use VML <v:fill> attributes (e.g. type, origin, position, aspect) to emulate cover/contain.
• 2026 validity: still relevant.
• Source: I got background-position and background-size working for Outlook for desktop 2007+ mjmlio/mjml#1814

7. Border radius / “bulletproof” buttons

• Symptom: rounded corners become square; padding/click-target inconsistencies.
• Affected: classic Outlook for Windows.
• Fix: VML <v:roundrect> button in an MSO conditional (plus HTML fallback).
• 2026 validity: still relevant for classic Outlook Win.
• Source: https://www.litmus.com/blog/a-guide-to-bulletproof-buttons-in-email-design/

8. VML layering is limited (background VML + VML button stacking can be tricky)

• Symptom: buttons/backgrounds don’t stack as expected.
• Affected: classic Outlook for Windows.
• Fix: avoid overlapping VML when possible; restructure layout (or accept non-rounded buttons over VML backgrounds).
• 2026 validity: still relevant.
• Sources: https://learn.microsoft.com/en-us/answers/questions/4674996/has-anyone-ever-work-with-layered-vml , https://help.knak.io/en/articles/11186499-common-outlook-faqs

Typography

9. Line-height quirks (Word engine)

• Symptom: cramped text, inconsistent leading.
• Affected: classic Outlook for Windows.
• Fix: add mso-line-height-rule: exactly; (sometimes at-least) on text blocks; keep typography inside table cells.
• 2026 validity: still relevant.
• Sources: https://stackoverflow.com/questions/8980956/line-height-not-working-in-outlook-2010-for-html-email , https://stackoverflow.com/questions/39143932/text-in-outlook-doesnt-use-line-height

10. Web fonts (@font-face) aren’t reliably supported

• Symptom: unexpected font fallbacks.
• Affected: classic Outlook Win (and many others).
• Fix: always provide a strong fallback stack; don’t assume webfonts.
• 2026 validity: still relevant.
• Source: https://www.campaignmonitor.com/css/text-fonts/font-face/

11. Lists (ul/ol) indentation + spacing are hard to control

• Symptom: misaligned bullets/indents; ignored styles.
• Affected: Outlook Win is a frequent pain point.
• Fix: conservative inline margin/padding on list elements; for pixel-perfect control, use “faux bullets” (table rows with a bullet cell).
• 2026 validity: still relevant.
• Source: https://www.litmus.com/blog/the-ultimate-guide-to-bulleted-lists-in-html-email/

Images + media

12. High-DPI / scaling issues

• Symptom: unexpected scaling / layout drift when Windows DPI ≠ 96.
• Affected: classic Outlook Win.
• Fix: use OfficeDocumentSettings PixelsPerInch=96 (helps some cases); design defensively and test at common DPI settings.
• 2026 validity: still relevant.
• Sources: https://www.litmus.com/blog/a-guide-to-rendering-differences-in-microsoft-outlook-clients , https://learn.microsoft.com/en-us/troubleshoot/outlook/user-interface/graphics-file-attachment-grows-larger-in-recipient-email

13. Image gaps / whitespace under images

• Symptom: 1px gaps between images or under an image.
• Affected: Outlook Win (and occasionally others depending on markup).
• Fix: img { display:block; } and set font-size:0; line-height:0; on the containing td when doing image-only cells.
• 2026 validity: still relevant.
• Source: https://stackoverflow.com/questions/19051547/html-mail-1px-vertical-space-between-images-in-outlook-2013

14. Animated GIFs show only the first frame

• Symptom: animation appears static.
• Affected: classic Outlook Win (Word engine).
• Fix: ensure the first frame contains the key message; optionally show an alternate static fallback for MSO.
• 2026 validity: still relevant for classic Outlook Win.
• Source: https://www.litmus.com/blog/a-guide-to-animated-gifs-in-email/

15. SVG support is inconsistent and (in newer Outlook surfaces) can be blocked

• Symptom: missing SVGs / blank space.
• Affected: varies; Outlook web/new Win has recent security-driven changes.
• Fix: prefer PNG/JPG; assume inline SVG is unsafe for Outlook.
• 2026 validity: relevant.
• Sources: https://www.caniemail.com/features/image-svg/ , https://www.techradar.com/pro/microsoft-outlook-will-no-longer-show-inline-svg-images-regularly-exploited-in-phishing-attacks

16. Image scaling quality (-ms-interpolation-mode: bicubic)

• Symptom: jagged downscaled images in some MS renderers.
• Affected: legacy MS/IE rendering paths.
• Fix: include img { -ms-interpolation-mode:bicubic; } in your baseline reset (low risk).
• 2026 validity: mostly “safe legacy hygiene”; still commonly kept in boilerplates.
• Source: https://learn.microsoft.com/en-us/openspecs/ie_standards/ms-css21e/baca27b8-6192-4c3e-af0b-9c0875ad7030

Visibility / hiding content

17. display:none isn’t always enough to hide content in Outlook Win

• Symptom: “hidden” blocks still appear or leave gaps.
• Affected: classic Outlook Win.
• Fix: add mso-hide:all; plus belt-and-suspenders hiding styles (max-height:0; overflow:hidden; font-size:0; line-height:0; opacity:0;) or use MSO conditionals for “not Outlook”.
• 2026 validity: still relevant.
• Source: https://www.copernica.com/en/news/post/quick-tip-how-to-hide-mobile-content-in-desktop-email-clients

Dark mode

18. Dark mode color overrides / inversions

• Symptom: brand colors mutate, backgrounds invert, logos become unreadable.
• Affected: Outlook desktop + Outlook web (different behaviors).
• Fix: layered mitigations: meta name="color-scheme", meta name="supported-color-schemes", progressive @media (prefers-color-scheme: dark), and client-specific hooks where applicable; expect testing to be necessary.
• 2026 validity: very relevant.
• Sources: https://support.microsoft.com/en-us/office/dark-mode-in-outlook-3e2446e0-9a7b-4189-9af9-57fb94d02ae3 , https://www.caniemail.com/features/css-at-media-prefers-color-scheme/

Legacy IE/Trident footnote

19. X-UA-Compatible: IE=edge breaks images in Windows Live Mail

• Symptom: broken images.
• Affected: Windows Live Mail / legacy Windows clients.
• Fix: wrap the meta tag in a conditional comment.
• 2026 validity: mostly legacy-only; worth documenting because the snippet still shows up in old guides.
• Source: https://www.emailonacid.com/blog/article/email-development/prevent-ie-edge-meta-tag-from-breaking-images-in-live-mail/

Helpful OSS “receipts” (active projects that still carry these hacks)

• MJML compatibility table (actively maintained, includes Outlook Windows): https://mjml.io/compatibility/mj-table
• MJML Outlook background issues/solutions (VML): Remove background support for mj-section for Outlook 16/Windows 10 mjmlio/mjml#467 , I got background-position and background-size working for Outlook for desktop 2007+ mjmlio/mjml#1814
• Foundation for Emails (tables-first framework built for Outlook constraints): https://github.com/foundation/foundation-emails

[charliecreates]

Report 2 — jsx-email (main branch) Outlook support: what’s there + improvement suggestions

What jsx-email already does well for Outlook / Word-engine clients

• VML namespaces on <html>: packages/jsx-email/src/components/html.tsx adds xmlns:o + xmlns:v (enables VML usage).
• OfficeDocumentSettings injection: packages/jsx-email/src/components/head.tsx injects MSO-only XML with AllowPNG + PixelsPerInch=96 (DPI/scaling mitigation).
• First-class conditional comments:
  • Component: packages/jsx-email/src/components/conditional.tsx
  • Renderer plugin: packages/jsx-email/src/renderer/conditional.ts
  • Supports a head prop to emit conditionals in the <head>.
• VML fallbacks in core components
  • Background: packages/jsx-email/src/components/background.tsx emits VML <v:rect> background fallback.
  • Button: packages/jsx-email/src/components/button.tsx emits a VML <v:roundrect> fallback.
  • Container: packages/jsx-email/src/components/container.tsx emits MSO-only wrapper tables for fixed widths.
• Renderer hygiene
  • packages/jsx-email/src/renderer/render.ts includes a rehype pipeline and moves <style> tags into <head>.
  • Optional inlining via packages/plugin-inline/src/index.ts.

Overall: the repo already has most of the right primitives (conditional comments + VML) that modern email frameworks rely on.

Gaps / risks I’d prioritize

P0 (correctness / potential breakage)

1. Button VML fallback appears to interpolate ${children} inside a string template

• Risk: if children is not a plain string (e.g. <Text>Buy</Text>), the VML-only path may output incorrect content.
• Suggestion: render children to an HTML string before injecting into the VML <center>.

2. Raw component unescape restores comment closers as "/-->"

• File: packages/jsx-email/src/renderer/raw.ts (unescapeForRawComponent)
• Risk: raw HTML containing --> may be mutated in a surprising / non-standard way.
• Suggestion: separate “conditional-comment raw” from “general raw HTML”, or restore comments exactly and only use the /--> variant where required.

3. Head duplicates multiple meta tags

• File: packages/jsx-email/src/components/head.tsx
• Suggestion: remove duplicates and add a snapshot test for canonical head output.

P1 (high-value defaults commonly used for Outlook)

4. Missing default Outlook table spacing reset (mso-table-lspace/rspace)

• Suggestion: provide an opt-out default reset style (or CssReset component) that includes:
  • table, td { mso-table-lspace:0pt; mso-table-rspace:0pt; border-collapse:collapse; }
  • img { -ms-interpolation-mode:bicubic; }
  • plus a minimal baseline (body margin/padding, etc.)

5. No explicit helper/guidance for Outlook line-height quirks

• Suggestion: add docs and/or a Text helper preset that can apply mso-line-height-rule: exactly.

P2 (DX improvements)

6. Ergonomic wrappers around Conditional

• Suggestion: small helpers like <MsoOnly> / <NotMso> (thin wrappers) so template authors don’t need to remember mso={false} patterns.

7. CSS inlining is destructive by design (removes <style> and strips classes)

• Suggestion: document this clearly, and consider an optional “hybrid inline” mode that preserves media queries / responsive style blocks.

If you want, I can open follow-up issues/PRs

• A small PR could address the P0 items (Button child rendering, Raw comment restoration, Head meta de-dupe) and add snapshot tests.