Fixing Compatibility Issues

How to use Emailens warnings and framework-aware code fixes to improve email client compatibility.

Workflow

Analyze your email with analyzeEmail() or the REST API
Review warnings grouped by severity (errors first)
Apply fixes using the fix code snippets — framework-aware when you specify a format
Re-analyze to verify improvements
Diff results using diffResults() to see what changed

Reading warnings

Each warning tells you exactly what's wrong:

{
  "severity": "error",
  "client": "outlook-windows-legacy",
  "property": "border-radius",
  "message": "border-radius is not supported in Outlook Classic (Word rendering engine)",
  "suggestion": "Use VML roundrect for rounded corners in Outlook",
  "fix": {
    "before": "<a href=\"...\" style=\"border-radius: 6px; ...\">Click Here</a>",
    "after": "<!--[if mso]><v:roundrect ...>...</v:roundrect><![endif]-->...",
    "language": "html",
    "description": "Use VML to render rounded buttons in Outlook"
  }
}

Framework-aware fixes

Pass your source framework to get fix snippets in your own language:

// Generic HTML fixes
const warnings = analyzeEmail(html);

// React Email fixes — uses Row, Column, Font, Img components
const warnings = analyzeEmail(html, "jsx");

// MJML fixes — uses mj-section, mj-column, mj-font elements
const warnings = analyzeEmail(html, "mjml");

// Maizzle fixes — uses Tailwind classes, MSO conditionals, config guidance
const warnings = analyzeEmail(html, "maizzle");

For example, display:flex in Outlook produces different fixes depending on your framework:

Framework	Fix style
(none)	HTML `<table>` with `<!--[if mso]>` conditional comments
`"jsx"`	React Email `<Row>` + `<Column>` components
`"mjml"`	MJML `<mj-section>` + `<mj-column>` elements
`"maizzle"`	Tailwind `w-1/2` classes with MSO conditional table

Priority order

Fix issues in this order:

Errors — broken layouts, missing content
Warnings — degraded appearance
Info — minor cosmetic differences

Focus on clients with the lowest scores first.

Common fixes

Flexbox — Table (HTML)

<!-- Before (broken in Gmail, Outlook) -->
<div style="display: flex; gap: 20px;">
  <div>Column 1</div>
  <div>Column 2</div>
</div>

<!-- After (works everywhere) -->
<table role="presentation" cellpadding="0" cellspacing="0">
  <tr>
    <td style="padding-right: 20px;">Column 1</td>
    <td>Column 2</td>
  </tr>
</table>

Flexbox — Row/Column (React Email)

// Before (broken in Outlook)
<div style={{ display: "flex", gap: "16px" }}>
  <div style={{ flex: 1 }}>Column 1</div>
  <div style={{ flex: 1 }}>Column 2</div>
</div>

// After (works everywhere)
import { Row, Column } from "@react-email/components";

<Row>
  <Column style={{ width: "50%", verticalAlign: "top" }}>Column 1</Column>
  <Column style={{ width: "50%", verticalAlign: "top" }}>Column 2</Column>
</Row>

Border-radius — Outlook VML

<!-- Before -->
<div style="background: #8a7544; border-radius: 8px; padding: 12px 24px;">
  <a href="#" style="color: white;">Click here</a>
</div>

<!-- After (with Outlook fallback) -->
<!--[if mso]>
<v:roundrect xmlns:v="urn:schemas-microsoft-com:vml" href="#" style="width:200px;height:44px;" arcsize="18%" fillcolor="#8a7544" stroke="f">
<v:textbox><center style="color:white;">Click here</center></v:textbox>
</v:roundrect>
<![endif]-->
<!--[if !mso]><!-->
<div style="background: #8a7544; border-radius: 8px; padding: 12px 24px;">
  <a href="#" style="color: white;">Click here</a>
</div>
<!--<![endif]-->

Automated fixing with LLMs

Use generateFixPrompt() to create a prompt for Claude or another LLM. The prompt includes framework-specific instructions when a format is specified:

import { analyzeEmail, generateCompatibilityScore, generateFixPrompt } from "@emailens/engine";

const warnings = analyzeEmail(html, "jsx");
const scores = generateCompatibilityScore(warnings);
const prompt = generateFixPrompt({
  originalHtml: jsxSource,
  warnings,
  scores,
  scope: "all",
  format: "jsx",
});

// Send prompt to your preferred LLM — it will suggest React Email-native fixes

Tracking progress

Use diffResults() to compare before and after:

import { transformForAllClients, diffResults } from "@emailens/engine";

const before = transformForAllClients(originalHtml);
const after = transformForAllClients(fixedHtml);
const diffs = diffResults(before, after);

for (const diff of diffs) {
  console.log(`${diff.clientId}: ${diff.scoreBefore} → ${diff.scoreAfter} (${diff.scoreDelta > 0 ? "+" : ""}${diff.scoreDelta})`);
}

Fixing Compatibility Issues

On this page