Email Client Compatibility Checks
Relevant source files
The following files were used as context for generating this wiki page:
Email Client Compatibility Checks identify HTML and CSS features that lack support in major email clients like Gmail, Outlook, and Apple Mail. The system analyzes React Email templates to detect potential rendering issues before delivery. It combines data from the "Can I Email" project with custom React Email constraints to provide real-time feedback during development.
The compatibility engine operates by parsing template source code into an Abstract Syntax Tree (AST) and comparing detected patterns against a database of known support limitations. Sources: packages/ui/src/actions/email-validation/check-compatibility.ts:108-115, skills/react-email/SKILL.md:144-150
Core Validation Logic
The checkCompatibility function serves as the primary entry point for validation. It processes the React code string and generates a ReadableStream of CompatibilityCheckingResult objects. Sources: packages/ui/src/actions/email-validation/check-compatibility.ts:108-112
Static Analysis Process
- AST Generation: The system uses
@babel/parserwithjsxandtypescriptplugins to convert the React code into a traversable tree. Sources: packages/ui/src/actions/email-validation/check-compatibility.ts:113-118 - Property Extraction: The
getUsedStylePropertiesutility scans the AST to extract all CSS properties applied viastyleattributes or Tailwind classes. Sources: packages/ui/src/actions/email-validation/check-compatibility.ts:131-135 - Entry Comparison: The engine iterates through
supportEntries(caniemail-data) andreactEmailSupportEntries(custom constraints). Sources: packages/ui/src/actions/email-validation/check-compatibility.ts:138-142 - Category Filtering: Checks are split into
htmlandcsscategories. HTML checks verify element names and attributes, while CSS checks verify property names, values, units, and functions. Sources: packages/ui/src/actions/email-validation/check-compatibility.ts:153-247
The diagram shows the sequential flow from raw React code to the generation of compatibility insights. Sources: packages/ui/src/actions/email-validation/check-compatibility.ts:108-285
Critical Compatibility Constraints
The project enforces specific rules based on email client rendering engine limitations, such as Outlook's use of Word for rendering. Sources: skills/react-email/TESTS.md:73-77
Unsupported Technologies
| Feature | Reason for Restriction | Alternative Recommendation |
|---|---|---|
| Flexbox/Grid | Not supported by Outlook (Word engine). | Use Row and Column components. |
| SVG/WEBP | Unreliable rendering in Gmail and Outlook. | Use PNG or JPEG formats. |
| Media Queries | Stripped by Gmail or ignored by Outlook. | Use mobile-first stacked layouts. |
| Dark Mode Selectors | dark: variants are not supported. | Apply dark colors directly to the theme. |
| rem units | Email clients do not support rem. | Use pixelBasedPreset to convert to pixels. |
Sources: skills/react-email/SKILL.md:144-159, skills/react-email/references/STYLING.md:25-40, skills/react-email/TESTS.md:105-110
Compatibility Result Data Structures
The check returns structured data containing the location of the issue and the level of support across different clients. Sources: packages/ui/src/actions/email-validation/check-compatibility.ts:31-37
Data Model: CompatibilityCheckingResult
| Field | Type | Description |
|---|---|---|
location | SourceLocation | The line and column in the source code. |
source | string | The snippet of source code causing the issue. |
entry | SupportEntry | The metadata for the unsupported feature. |
status | SupportStatus | The severity level (e.g., error, warning). |
statsPerEmailClient | CompatibilityStats | Detailed support status per client family. |
Sources: packages/ui/src/actions/email-validation/check-compatibility.ts:31-37
User Interface Integration
Compatibility results are surfaced in the react-email toolbar. The "Copy for AI" feature utilizes these results to generate prompts for LLMs to fix detected issues. Sources: packages/ui/src/components/toolbar/copy-for-ai.tsx:88-100
This sequence illustrates how validation results are converted into actionable AI prompts within the UI. Sources: packages/ui/src/components/toolbar/copy-for-ai.tsx:112-136
AI Prompt Generation
When errors are detected, the system generates a prompt instructing the AI to:
- Explain which email clients are affected.
- Provide fallbacks or alternative approaches (e.g., table-based layouts).
- Suggest email-safe CSS properties.
Sources: packages/ui/src/components/toolbar/copy-for-ai.tsx:130-135
Configuration and Defaults
The validation engine defaults to checking against gmail, apple-mail, outlook, and yahoo. Users can narrow these checks using the --clients CLI flag or the COMPATIBILITY_EMAIL_CLIENTS environment variable. Sources: packages/ui/CHANGELOG.md:143-149
Summary of Detection Capabilities
- HTML Elements: Detects unsupported tags (e.g.,
<svg>). - CSS Properties: Detects layout properties (e.g.,
display: flex) and color formats (e.g.,hsl/hsla). - Units: Identifies unsupported units like
rem. - Functions: Validates CSS functions against known support data.
Sources: packages/ui/src/actions/email-validation/check-compatibility.ts:153-247, packages/ui/CHANGELOG.md:175-175