@emailens/engine 0.11.8 → 0.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +264 -264
- package/dist/compile/index.d.cts +2 -2
- package/dist/compile/index.d.ts +2 -2
- package/dist/index.cjs +2606 -142
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +7 -59
- package/dist/index.d.ts +7 -59
- package/dist/index.js +2596 -142
- package/dist/index.js.map +1 -1
- package/dist/{react-email-B82A1R_K.d.ts → react-email-BzyXjPrH.d.ts} +1 -1
- package/dist/{react-email-DRkmpgX-.d.cts → react-email-DHkCZ7TG.d.cts} +1 -1
- package/dist/server.d.cts +1 -1
- package/dist/server.d.ts +1 -1
- package/dist/{types-DiseE-UH.d.cts → types-edFeUest.d.cts} +88 -2
- package/dist/{types-DiseE-UH.d.ts → types-edFeUest.d.ts} +88 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,264 +1,264 @@
|
|
|
1
|
-
<div align="center">
|
|
2
|
-
|
|
3
|
-
<picture>
|
|
4
|
-
<source media="(prefers-color-scheme: dark)" srcset="./docs/wordmark-dark.svg">
|
|
5
|
-
<img src="./docs/wordmark-light.svg" alt="emailens / engine" width="515">
|
|
6
|
-
</picture>
|
|
7
|
-
|
|
8
|
-
**The rendering linter for email**
|
|
9
|
-
|
|
10
|
-
[](https://github.com/emailens/engine/actions/workflows/ci.yml)
|
|
11
|
-
[](https://www.npmjs.com/package/@emailens/engine)
|
|
12
|
-
[](./LICENSE)
|
|
13
|
-
[]()
|
|
14
|
-
[](https://nodejs.org/)
|
|
15
|
-
[](https://github.com/emailens/mcp)
|
|
16
|
-
[](https://github.com/emailens/engine/stargazers)
|
|
17
|
-
|
|
18
|
-
[Quick Start](#quick-start) · [What It Catches](#what-it-catches) · [Why Emailens](#why-emailens) · [Supported Clients](#supported-email-clients) · [API Docs](./docs/API.md) · [The State of Email CSS](https://emailens.dev/email-css/report)
|
|
19
|
-
|
|
20
|
-
</div>
|
|
21
|
-
|
|
22
|
-
**Your email looks perfect in Apple Mail. Gmail strips half the CSS. Outlook renders it in Word.**
|
|
23
|
-
|
|
24
|
-
`@emailens/engine` analyzes your email against
|
|
25
|
-
|
|
26
|
-
Write it however you like. **HTML, MJML, Maizzle and React Email** all go in the front: the engine compiles the template with your own compiler and lints the HTML that actually gets sent, which is the only version your reader sees.
|
|
27
|
-
|
|
28
|
-
Our data says you need this: of those
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
> **[emailens.dev](https://emailens.dev)**: Try the hosted version. Paste HTML, get a full audit in seconds.
|
|
33
|
-
|
|
34
|
-
## Quick Start
|
|
35
|
-
|
|
36
|
-
No install, no project setup, lint any email right now:
|
|
37
|
-
|
|
38
|
-
```bash
|
|
39
|
-
npx @emailens/cli lint email.html
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
-
Or use the engine as a library:
|
|
43
|
-
|
|
44
|
-
```bash
|
|
45
|
-
npm install @emailens/engine
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
```typescript
|
|
49
|
-
import { auditEmail } from "@emailens/engine";
|
|
50
|
-
|
|
51
|
-
// Flexbox + gap + box-shadow — all Outlook killers
|
|
52
|
-
const html = `<html lang="en">
|
|
53
|
-
<head><title>Weekly Update</title>
|
|
54
|
-
<style>
|
|
55
|
-
.card { border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.1); }
|
|
56
|
-
</style>
|
|
57
|
-
</head>
|
|
58
|
-
<body>
|
|
59
|
-
<div class="card" style="display: flex; gap: 16px;">
|
|
60
|
-
<div>Column A</div>
|
|
61
|
-
<div>Column B</div>
|
|
62
|
-
</div>
|
|
63
|
-
</body>
|
|
64
|
-
</html>`;
|
|
65
|
-
|
|
66
|
-
const report = auditEmail(html, { framework: "jsx" });
|
|
67
|
-
|
|
68
|
-
console.log(report.compatibility.scores["outlook-windows"]);
|
|
69
|
-
// { score: 30, errors: 3, warnings: 3, info: 1 }
|
|
70
|
-
// ↑ Outlook uses Word — flexbox, gap, box-shadow, border-radius all break
|
|
71
|
-
|
|
72
|
-
console.log(report.compatibility.scores["gmail-web"]);
|
|
73
|
-
// { score: 75, errors: 0, warnings: 5, info: 0 }
|
|
74
|
-
|
|
75
|
-
console.log(report.spam.score); // 100 (clean)
|
|
76
|
-
console.log(report.accessibility.score); // 88
|
|
77
|
-
console.log(report.size.clipped); // false (under Gmail's 102KB limit)
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
## Score too low? Fix it
|
|
81
|
-
|
|
82
|
-
Score too low? Fix it automatically:
|
|
83
|
-
|
|
84
|
-
```typescript
|
|
85
|
-
import { generateAiFix, AI_FIX_SYSTEM_PROMPT } from "@emailens/engine";
|
|
86
|
-
|
|
87
|
-
const { code } = await generateAiFix({
|
|
88
|
-
originalHtml: html,
|
|
89
|
-
warnings: report.compatibility.warnings,
|
|
90
|
-
scores: report.compatibility.scores,
|
|
91
|
-
scope: "outlook-windows",
|
|
92
|
-
format: "jsx",
|
|
93
|
-
provider: async (prompt) => {
|
|
94
|
-
// Any LLM — Claude, GPT, etc.
|
|
95
|
-
const msg = await anthropic.messages.create({
|
|
96
|
-
model: "claude-sonnet-4-6",
|
|
97
|
-
max_tokens: 8192,
|
|
98
|
-
system: AI_FIX_SYSTEM_PROMPT,
|
|
99
|
-
messages: [{ role: "user", content: prompt }],
|
|
100
|
-
});
|
|
101
|
-
return msg.content[0].type === "text" ? msg.content[0].text : "";
|
|
102
|
-
},
|
|
103
|
-
});
|
|
104
|
-
// code → JSX with <Table> layout, VML roundrects, inline fallbacks
|
|
105
|
-
```
|
|
106
|
-
|
|
107
|
-
## What It Catches
|
|
108
|
-
|
|
109
|
-
14 analysis engines, one `auditEmail()` call.
|
|
110
|
-
|
|
111
|
-
- **CSS compatibility**:
|
|
112
|
-
- **Outlook VML**: structural faults in the Outlook-only markup inside `<!--[if mso]>` conditional comments — the one part of an email a DOM analyzer structurally cannot see, since to every HTML parser it is a comment node and to a screenshot it does not exist
|
|
113
|
-
- **Content overflow**: fixed widths wider than the email frame and unbreakable strings that force horizontal scrolling
|
|
114
|
-
- **Visual bugs**: gradients/background images with no color fallback (invisible content in Outlook) and fonts with no web-safe fallback, each with a concrete fix
|
|
115
|
-
- **Design consistency**: colours that differ as values but not to a reader (OKLab distance), and runaway cardinality in type sizes, families and corner radii
|
|
116
|
-
- **Dark and mobile contrast**: the two renders nobody checks — what a client's forced inversion does, what the email's own `prefers-color-scheme` block does, and what changes below the mobile breakpoint
|
|
117
|
-
- **Spam scoring**: 45+ signals modeled after SpamAssassin, CAN-SPAM, and GDPR
|
|
118
|
-
- **Accessibility**: WCAG contrast ratios, alt text, semantic structure, heading hierarchy
|
|
119
|
-
- **Link validation**: broken hrefs, insecure HTTP, `javascript:` protocols, deceptive URLs
|
|
120
|
-
- **Image analysis**: missing dimensions, oversized data URIs, tracking pixels, WebP/SVG format
|
|
121
|
-
- **Inbox preview**: subject/preheader truncation per client, Gmail clipping detection
|
|
122
|
-
- **Domain authentication**: SPF, DKIM, DMARC, MX, and BIMI DNS record validation
|
|
123
|
-
- **Template variables**: unresolved merge tags across 6 template systems (Handlebars, ERB, Mailchimp, etc.)
|
|
124
|
-
|
|
125
|
-
Every finding can carry its **source position**: line, column and offset, plus
|
|
126
|
-
every place it occurs, so a result can be pointed at, annotated on a pull
|
|
127
|
-
request, or fixed in place:
|
|
128
|
-
|
|
129
|
-
```typescript
|
|
130
|
-
const report = auditEmail(html, { positions: true });
|
|
131
|
-
const w = report.compatibility.warnings[0];
|
|
132
|
-
`${file}:${w.loc.line}:${w.loc.column}`; // emails/welcome.html:42:8
|
|
133
|
-
w.locs.length; // every element it breaks on
|
|
134
|
-
```
|
|
135
|
-
|
|
136
|
-
## Installation
|
|
137
|
-
|
|
138
|
-
```bash
|
|
139
|
-
npm install @emailens/engine
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
Three entry points:
|
|
143
|
-
|
|
144
|
-
| Import | Description |
|
|
145
|
-
|---|---|
|
|
146
|
-
| `@emailens/engine` | Core analysis: CSS, spam, a11y, links, images, inbox preview, size, templates, AI fix |
|
|
147
|
-
| `@emailens/engine/compile` | JSX / MJML / Maizzle → HTML compilers |
|
|
148
|
-
| `@emailens/engine/server` | Node-only: DNS deliverability checks, SpamAssassin integration |
|
|
149
|
-
|
|
150
|
-
## Why Emailens?
|
|
151
|
-
|
|
152
|
-
- **Offline-first**: runs entirely locally, no network calls required (except DNS deliverability checks)
|
|
153
|
-
- **Unified audit**: one function call returns CSS compatibility, spam, accessibility, links, images, inbox preview, size, and template checks
|
|
154
|
-
- **Framework-aware**: fix snippets tailored to React Email (JSX), MJML, and Maizzle
|
|
155
|
-
- **AI-ready**: structural issues get LLM-powered auto-fix with any provider (Claude, GPT, etc.)
|
|
156
|
-
- **Programmable**: a TypeScript API, not a GUI. Drops into CI, editors, or build pipelines
|
|
157
|
-
|
|
158
|
-
| | @emailens/engine | Litmus | Email on Acid | caniemail.com |
|
|
159
|
-
|---|---|---|---|---|
|
|
160
|
-
| Local/offline | Yes | No | No | Data only |
|
|
161
|
-
| Programmatic API | Yes | Limited | No | No |
|
|
162
|
-
| CSS + Spam + A11y | Yes | Separate tools | Separate tools | CSS only |
|
|
163
|
-
| AI auto-fix | Yes | No | No | No |
|
|
164
|
-
| Open source | MIT | No | No | Yes (data) |
|
|
165
|
-
|
|
166
|
-
### vs other email libraries
|
|
167
|
-
|
|
168
|
-
`@emailens/engine` sits in the **QA / lint / scoring** slot: it analyzes finished HTML. It's complementary to (not a replacement for) composition and inlining libraries.
|
|
169
|
-
|
|
170
|
-
| | @emailens/engine | [juice](https://github.com/automattic/juice) | [email-comb](https://github.com/codsen/email-comb) | [mjml](https://mjml.io/) | [maizzle](https://maizzle.com/) |
|
|
171
|
-
|---|---|---|---|---|---|
|
|
172
|
-
| Purpose | QA / lint / score | CSS inliner | Unused CSS pruner | MJML → HTML | Tailwind → HTML |
|
|
173
|
-
| Per-client compatibility scoring | Yes | No | No | No | No |
|
|
174
|
-
| Spam / a11y / link / image analysis | Yes | No | No | No | No |
|
|
175
|
-
| AI-powered fix generation | Yes | No | No | No | No |
|
|
176
|
-
| Compose emails | Reads only | Reads only | Reads only | Yes | Yes |
|
|
177
|
-
| CSS inlining | No (pair with juice) | Yes | No | Yes (built-in) | Yes (built-in) |
|
|
178
|
-
|
|
179
|
-
A typical pipeline: write in **mjml** or **maizzle** → inline with **juice** → audit with **@emailens/engine** → ship.
|
|
180
|
-
|
|
181
|
-
## Supported Email Clients
|
|
182
|
-
|
|
183
|
-
| Client | ID | Category | Engine | Dark Mode |
|
|
184
|
-
|---|---|---|---|---|
|
|
185
|
-
| Gmail | `gmail-web` | Webmail | Gmail Web | Yes |
|
|
186
|
-
| Gmail Android | `gmail-android` | Mobile | Gmail Mobile | Yes |
|
|
187
|
-
| Gmail iOS | `gmail-ios` | Mobile | Gmail Mobile | Yes |
|
|
188
|
-
| Outlook 365 | `outlook-web` | Webmail | Outlook Web | Yes |
|
|
189
|
-
| Outlook (New) | `outlook-windows` | Desktop | Outlook Web | Yes |
|
|
190
|
-
| Outlook Classic | `outlook-windows-legacy` | Desktop | Microsoft Word | Yes |
|
|
191
|
-
| Outlook iOS | `outlook-ios` | Mobile | Outlook Mobile | Yes |
|
|
192
|
-
| Outlook Android | `outlook-android` | Mobile | Outlook Mobile | Yes |
|
|
193
|
-
| Outlook for Mac | `outlook-macos` | Desktop | WebKit | Yes |
|
|
194
|
-
| Apple Mail | `apple-mail-macos` | Desktop | WebKit | Yes |
|
|
195
|
-
| Apple Mail iOS | `apple-mail-ios` | Mobile | WebKit | Yes |
|
|
196
|
-
| Yahoo Mail | `yahoo-mail` | Webmail | Yahoo | Yes |
|
|
197
|
-
| Yahoo Mail Android | `yahoo-mail-android` | Mobile | Yahoo | Yes |
|
|
198
|
-
| Yahoo Mail iOS | `yahoo-mail-ios` | Mobile | Yahoo | Yes |
|
|
199
|
-
| Samsung Mail | `samsung-mail` | Mobile | Samsung | Yes |
|
|
200
|
-
| Thunderbird | `thunderbird` | Desktop | Gecko | No |
|
|
201
|
-
| HEY Mail | `hey-mail` | Webmail | WebKit | Yes |
|
|
202
|
-
| Proton Mail | `protonmail` | Webmail | Proton | Yes |
|
|
203
|
-
| AOL Mail | `aol` | Webmail | AOL | Yes |
|
|
204
|
-
| Fastmail | `fastmail` | Webmail | Fastmail | Yes |
|
|
205
|
-
| Superhuman | `superhuman` | Desktop | Blink | Yes |
|
|
206
|
-
|
|
207
|
-
## API Documentation
|
|
208
|
-
|
|
209
|
-
Full API reference: **[docs/API.md](./docs/API.md)**
|
|
210
|
-
|
|
211
|
-
Covers:
|
|
212
|
-
- `auditEmail` and `createSession`: core analysis
|
|
213
|
-
- Standalone analyzers (CSS, VML, spam, links, accessibility, images, inbox preview, size, templates)
|
|
214
|
-
- DNS deliverability and SpamAssassin integration
|
|
215
|
-
- Client transforms and dark mode simulation
|
|
216
|
-
- Compile module (JSX, MJML, Maizzle)
|
|
217
|
-
- AI-powered fixes and token estimation
|
|
218
|
-
- Performance optimization guide
|
|
219
|
-
- Security considerations
|
|
220
|
-
- Full TypeScript type definitions
|
|
221
|
-
|
|
222
|
-
## Roadmap
|
|
223
|
-
|
|
224
|
-
See [ROADMAP.md](./ROADMAP.md) for the full picture (shipped items + items under consideration with rationale).
|
|
225
|
-
|
|
226
|
-
**Shipped:** Outlook VML structural validation (`checkVml`, verified against the Word engine) · automated caniemail.com data sync · GitHub Actions integration via `@emailens/cli` and the [Marketplace Action](https://github.com/marketplace/actions/emailens-email-preview-check) · AI-powered fix generation · compile module for JSX/MJML/Maizzle.
|
|
227
|
-
|
|
228
|
-
**Considering:** Outlook VML auto-generation · plugin system for custom analyzers · MJML/Maizzle source-level linting · ESLint plugin · spam corpus tuning · dark-mode accuracy tests.
|
|
229
|
-
|
|
230
|
-
Concrete bugs go in [Issues](https://github.com/emailens/engine/issues). Open-ended ideas live in the roadmap.
|
|
231
|
-
|
|
232
|
-
## Contributing
|
|
233
|
-
|
|
234
|
-
Contributions are welcome! See **[CONTRIBUTING.md](./CONTRIBUTING.md)** for architecture overview, setup instructions, and PR guidelines.
|
|
235
|
-
|
|
236
|
-
```bash
|
|
237
|
-
bun install && bun test # 719 tests
|
|
238
|
-
```
|
|
239
|
-
|
|
240
|
-
Optional real-render validation: renders engine output in a real browser engine (free, no Litmus/Email on Acid needed). Off by default; needs a browser-capable machine:
|
|
241
|
-
|
|
242
|
-
```bash
|
|
243
|
-
bunx playwright install chromium
|
|
244
|
-
bun run test:render
|
|
245
|
-
```
|
|
246
|
-
|
|
247
|
-
### Data Maintenance
|
|
248
|
-
|
|
249
|
-
CSS support data is auto-synced from [caniemail.com](https://www.caniemail.com/). Other data (dark mode behavior, display limits, Superhuman overrides) is manually curated and tracked with verification dates.
|
|
250
|
-
|
|
251
|
-
```bash
|
|
252
|
-
bun run sync:caniemail # Refresh CSS support matrix from caniemail.com
|
|
253
|
-
bun run check:freshness # Flag stale data sources (exits 1 if any overdue)
|
|
254
|
-
```
|
|
255
|
-
|
|
256
|
-
See [CONTRIBUTING.md](./CONTRIBUTING.md#data-sources-and-freshness) for full details on data sources and verification procedures.
|
|
257
|
-
|
|
258
|
-
## License
|
|
259
|
-
|
|
260
|
-
MIT, Copyright 2025 [Emailens](https://emailens.dev)
|
|
261
|
-
|
|
262
|
-
---
|
|
263
|
-
|
|
264
|
-
If this saved you from an Outlook surprise, [a star](https://github.com/emailens/engine) helps other email developers find it.
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
<picture>
|
|
4
|
+
<source media="(prefers-color-scheme: dark)" srcset="./docs/wordmark-dark.svg">
|
|
5
|
+
<img src="./docs/wordmark-light.svg" alt="emailens / engine" width="515">
|
|
6
|
+
</picture>
|
|
7
|
+
|
|
8
|
+
**The rendering linter for email**
|
|
9
|
+
|
|
10
|
+
[](https://github.com/emailens/engine/actions/workflows/ci.yml)
|
|
11
|
+
[](https://www.npmjs.com/package/@emailens/engine)
|
|
12
|
+
[](./LICENSE)
|
|
13
|
+
[]()
|
|
14
|
+
[](https://nodejs.org/)
|
|
15
|
+
[](https://github.com/emailens/mcp)
|
|
16
|
+
[](https://github.com/emailens/engine/stargazers)
|
|
17
|
+
|
|
18
|
+
[Quick Start](#quick-start) · [What It Catches](#what-it-catches) · [Why Emailens](#why-emailens) · [Supported Clients](#supported-email-clients) · [API Docs](./docs/API.md) · [The State of Email CSS](https://emailens.dev/email-css/report)
|
|
19
|
+
|
|
20
|
+
</div>
|
|
21
|
+
|
|
22
|
+
**Your email looks perfect in Apple Mail. Gmail strips half the CSS. Outlook renders it in Word.**
|
|
23
|
+
|
|
24
|
+
`@emailens/engine` analyzes your email against 298 CSS and HTML features (plus 14 image formats) across 21 email clients, scores compatibility, and shows you exactly what to fix: before you hit send.
|
|
25
|
+
|
|
26
|
+
Write it however you like. **HTML, MJML, Maizzle and React Email** all go in the front: the engine compiles the template with your own compiler and lints the HTML that actually gets sent, which is the only version your reader sees.
|
|
27
|
+
|
|
28
|
+
Our data says you need this: of those 298 features, **only 6 are fully supported in every one of the 21 clients**. See [The State of Email CSS](https://emailens.dev/email-css/report).
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
> **[emailens.dev](https://emailens.dev)**: Try the hosted version. Paste HTML, get a full audit in seconds.
|
|
33
|
+
|
|
34
|
+
## Quick Start
|
|
35
|
+
|
|
36
|
+
No install, no project setup, lint any email right now:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
npx @emailens/cli lint email.html
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Or use the engine as a library:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
npm install @emailens/engine
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
```typescript
|
|
49
|
+
import { auditEmail } from "@emailens/engine";
|
|
50
|
+
|
|
51
|
+
// Flexbox + gap + box-shadow — all Outlook killers
|
|
52
|
+
const html = `<html lang="en">
|
|
53
|
+
<head><title>Weekly Update</title>
|
|
54
|
+
<style>
|
|
55
|
+
.card { border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.1); }
|
|
56
|
+
</style>
|
|
57
|
+
</head>
|
|
58
|
+
<body>
|
|
59
|
+
<div class="card" style="display: flex; gap: 16px;">
|
|
60
|
+
<div>Column A</div>
|
|
61
|
+
<div>Column B</div>
|
|
62
|
+
</div>
|
|
63
|
+
</body>
|
|
64
|
+
</html>`;
|
|
65
|
+
|
|
66
|
+
const report = auditEmail(html, { framework: "jsx" });
|
|
67
|
+
|
|
68
|
+
console.log(report.compatibility.scores["outlook-windows"]);
|
|
69
|
+
// { score: 30, errors: 3, warnings: 3, info: 1 }
|
|
70
|
+
// ↑ Outlook uses Word — flexbox, gap, box-shadow, border-radius all break
|
|
71
|
+
|
|
72
|
+
console.log(report.compatibility.scores["gmail-web"]);
|
|
73
|
+
// { score: 75, errors: 0, warnings: 5, info: 0 }
|
|
74
|
+
|
|
75
|
+
console.log(report.spam.score); // 100 (clean)
|
|
76
|
+
console.log(report.accessibility.score); // 88
|
|
77
|
+
console.log(report.size.clipped); // false (under Gmail's 102KB limit)
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## Score too low? Fix it
|
|
81
|
+
|
|
82
|
+
Score too low? Fix it automatically:
|
|
83
|
+
|
|
84
|
+
```typescript
|
|
85
|
+
import { generateAiFix, AI_FIX_SYSTEM_PROMPT } from "@emailens/engine";
|
|
86
|
+
|
|
87
|
+
const { code } = await generateAiFix({
|
|
88
|
+
originalHtml: html,
|
|
89
|
+
warnings: report.compatibility.warnings,
|
|
90
|
+
scores: report.compatibility.scores,
|
|
91
|
+
scope: "outlook-windows",
|
|
92
|
+
format: "jsx",
|
|
93
|
+
provider: async (prompt) => {
|
|
94
|
+
// Any LLM — Claude, GPT, etc.
|
|
95
|
+
const msg = await anthropic.messages.create({
|
|
96
|
+
model: "claude-sonnet-4-6",
|
|
97
|
+
max_tokens: 8192,
|
|
98
|
+
system: AI_FIX_SYSTEM_PROMPT,
|
|
99
|
+
messages: [{ role: "user", content: prompt }],
|
|
100
|
+
});
|
|
101
|
+
return msg.content[0].type === "text" ? msg.content[0].text : "";
|
|
102
|
+
},
|
|
103
|
+
});
|
|
104
|
+
// code → JSX with <Table> layout, VML roundrects, inline fallbacks
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## What It Catches
|
|
108
|
+
|
|
109
|
+
14 analysis engines, one `auditEmail()` call.
|
|
110
|
+
|
|
111
|
+
- **CSS compatibility**: 298 CSS and HTML features tested across 21 email clients, with fix snippets and AI-powered auto-fix
|
|
112
|
+
- **Outlook VML**: structural faults in the Outlook-only markup inside `<!--[if mso]>` conditional comments — the one part of an email a DOM analyzer structurally cannot see, since to every HTML parser it is a comment node and to a screenshot it does not exist
|
|
113
|
+
- **Content overflow**: fixed widths wider than the email frame and unbreakable strings that force horizontal scrolling
|
|
114
|
+
- **Visual bugs**: gradients/background images with no color fallback (invisible content in Outlook) and fonts with no web-safe fallback, each with a concrete fix
|
|
115
|
+
- **Design consistency**: colours that differ as values but not to a reader (OKLab distance), and runaway cardinality in type sizes, families and corner radii
|
|
116
|
+
- **Dark and mobile contrast**: the two renders nobody checks — what a client's forced inversion does, what the email's own `prefers-color-scheme` block does, and what changes below the mobile breakpoint
|
|
117
|
+
- **Spam scoring**: 45+ signals modeled after SpamAssassin, CAN-SPAM, and GDPR
|
|
118
|
+
- **Accessibility**: WCAG contrast ratios, alt text, semantic structure, heading hierarchy
|
|
119
|
+
- **Link validation**: broken hrefs, insecure HTTP, `javascript:` protocols, deceptive URLs
|
|
120
|
+
- **Image analysis**: missing dimensions, oversized data URIs, tracking pixels, WebP/SVG format
|
|
121
|
+
- **Inbox preview**: subject/preheader truncation per client, Gmail clipping detection
|
|
122
|
+
- **Domain authentication**: SPF, DKIM, DMARC, MX, and BIMI DNS record validation
|
|
123
|
+
- **Template variables**: unresolved merge tags across 6 template systems (Handlebars, ERB, Mailchimp, etc.)
|
|
124
|
+
|
|
125
|
+
Every finding can carry its **source position**: line, column and offset, plus
|
|
126
|
+
every place it occurs, so a result can be pointed at, annotated on a pull
|
|
127
|
+
request, or fixed in place:
|
|
128
|
+
|
|
129
|
+
```typescript
|
|
130
|
+
const report = auditEmail(html, { positions: true });
|
|
131
|
+
const w = report.compatibility.warnings[0];
|
|
132
|
+
`${file}:${w.loc.line}:${w.loc.column}`; // emails/welcome.html:42:8
|
|
133
|
+
w.locs.length; // every element it breaks on
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
## Installation
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
npm install @emailens/engine
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Three entry points:
|
|
143
|
+
|
|
144
|
+
| Import | Description |
|
|
145
|
+
|---|---|
|
|
146
|
+
| `@emailens/engine` | Core analysis: CSS, spam, a11y, links, images, inbox preview, size, templates, AI fix |
|
|
147
|
+
| `@emailens/engine/compile` | JSX / MJML / Maizzle → HTML compilers |
|
|
148
|
+
| `@emailens/engine/server` | Node-only: DNS deliverability checks, SpamAssassin integration |
|
|
149
|
+
|
|
150
|
+
## Why Emailens?
|
|
151
|
+
|
|
152
|
+
- **Offline-first**: runs entirely locally, no network calls required (except DNS deliverability checks)
|
|
153
|
+
- **Unified audit**: one function call returns CSS compatibility, spam, accessibility, links, images, inbox preview, size, and template checks
|
|
154
|
+
- **Framework-aware**: fix snippets tailored to React Email (JSX), MJML, and Maizzle
|
|
155
|
+
- **AI-ready**: structural issues get LLM-powered auto-fix with any provider (Claude, GPT, etc.)
|
|
156
|
+
- **Programmable**: a TypeScript API, not a GUI. Drops into CI, editors, or build pipelines
|
|
157
|
+
|
|
158
|
+
| | @emailens/engine | Litmus | Email on Acid | caniemail.com |
|
|
159
|
+
|---|---|---|---|---|
|
|
160
|
+
| Local/offline | Yes | No | No | Data only |
|
|
161
|
+
| Programmatic API | Yes | Limited | No | No |
|
|
162
|
+
| CSS + Spam + A11y | Yes | Separate tools | Separate tools | CSS only |
|
|
163
|
+
| AI auto-fix | Yes | No | No | No |
|
|
164
|
+
| Open source | MIT | No | No | Yes (data) |
|
|
165
|
+
|
|
166
|
+
### vs other email libraries
|
|
167
|
+
|
|
168
|
+
`@emailens/engine` sits in the **QA / lint / scoring** slot: it analyzes finished HTML. It's complementary to (not a replacement for) composition and inlining libraries.
|
|
169
|
+
|
|
170
|
+
| | @emailens/engine | [juice](https://github.com/automattic/juice) | [email-comb](https://github.com/codsen/email-comb) | [mjml](https://mjml.io/) | [maizzle](https://maizzle.com/) |
|
|
171
|
+
|---|---|---|---|---|---|
|
|
172
|
+
| Purpose | QA / lint / score | CSS inliner | Unused CSS pruner | MJML → HTML | Tailwind → HTML |
|
|
173
|
+
| Per-client compatibility scoring | Yes | No | No | No | No |
|
|
174
|
+
| Spam / a11y / link / image analysis | Yes | No | No | No | No |
|
|
175
|
+
| AI-powered fix generation | Yes | No | No | No | No |
|
|
176
|
+
| Compose emails | Reads only | Reads only | Reads only | Yes | Yes |
|
|
177
|
+
| CSS inlining | No (pair with juice) | Yes | No | Yes (built-in) | Yes (built-in) |
|
|
178
|
+
|
|
179
|
+
A typical pipeline: write in **mjml** or **maizzle** → inline with **juice** → audit with **@emailens/engine** → ship.
|
|
180
|
+
|
|
181
|
+
## Supported Email Clients
|
|
182
|
+
|
|
183
|
+
| Client | ID | Category | Engine | Dark Mode |
|
|
184
|
+
|---|---|---|---|---|
|
|
185
|
+
| Gmail | `gmail-web` | Webmail | Gmail Web | Yes |
|
|
186
|
+
| Gmail Android | `gmail-android` | Mobile | Gmail Mobile | Yes |
|
|
187
|
+
| Gmail iOS | `gmail-ios` | Mobile | Gmail Mobile | Yes |
|
|
188
|
+
| Outlook 365 | `outlook-web` | Webmail | Outlook Web | Yes |
|
|
189
|
+
| Outlook (New) | `outlook-windows` | Desktop | Outlook Web | Yes |
|
|
190
|
+
| Outlook Classic | `outlook-windows-legacy` | Desktop | Microsoft Word | Yes |
|
|
191
|
+
| Outlook iOS | `outlook-ios` | Mobile | Outlook Mobile | Yes |
|
|
192
|
+
| Outlook Android | `outlook-android` | Mobile | Outlook Mobile | Yes |
|
|
193
|
+
| Outlook for Mac | `outlook-macos` | Desktop | WebKit | Yes |
|
|
194
|
+
| Apple Mail | `apple-mail-macos` | Desktop | WebKit | Yes |
|
|
195
|
+
| Apple Mail iOS | `apple-mail-ios` | Mobile | WebKit | Yes |
|
|
196
|
+
| Yahoo Mail | `yahoo-mail` | Webmail | Yahoo | Yes |
|
|
197
|
+
| Yahoo Mail Android | `yahoo-mail-android` | Mobile | Yahoo | Yes |
|
|
198
|
+
| Yahoo Mail iOS | `yahoo-mail-ios` | Mobile | Yahoo | Yes |
|
|
199
|
+
| Samsung Mail | `samsung-mail` | Mobile | Samsung | Yes |
|
|
200
|
+
| Thunderbird | `thunderbird` | Desktop | Gecko | No |
|
|
201
|
+
| HEY Mail | `hey-mail` | Webmail | WebKit | Yes |
|
|
202
|
+
| Proton Mail | `protonmail` | Webmail | Proton | Yes |
|
|
203
|
+
| AOL Mail | `aol` | Webmail | AOL | Yes |
|
|
204
|
+
| Fastmail | `fastmail` | Webmail | Fastmail | Yes |
|
|
205
|
+
| Superhuman | `superhuman` | Desktop | Blink | Yes |
|
|
206
|
+
|
|
207
|
+
## API Documentation
|
|
208
|
+
|
|
209
|
+
Full API reference: **[docs/API.md](./docs/API.md)**
|
|
210
|
+
|
|
211
|
+
Covers:
|
|
212
|
+
- `auditEmail` and `createSession`: core analysis
|
|
213
|
+
- Standalone analyzers (CSS, VML, spam, links, accessibility, images, inbox preview, size, templates)
|
|
214
|
+
- DNS deliverability and SpamAssassin integration
|
|
215
|
+
- Client transforms and dark mode simulation
|
|
216
|
+
- Compile module (JSX, MJML, Maizzle)
|
|
217
|
+
- AI-powered fixes and token estimation
|
|
218
|
+
- Performance optimization guide
|
|
219
|
+
- Security considerations
|
|
220
|
+
- Full TypeScript type definitions
|
|
221
|
+
|
|
222
|
+
## Roadmap
|
|
223
|
+
|
|
224
|
+
See [ROADMAP.md](./ROADMAP.md) for the full picture (shipped items + items under consideration with rationale).
|
|
225
|
+
|
|
226
|
+
**Shipped:** Outlook VML structural validation (`checkVml`, verified against the Word engine) · automated caniemail.com data sync · GitHub Actions integration via `@emailens/cli` and the [Marketplace Action](https://github.com/marketplace/actions/emailens-email-preview-check) · AI-powered fix generation · compile module for JSX/MJML/Maizzle.
|
|
227
|
+
|
|
228
|
+
**Considering:** Outlook VML auto-generation · plugin system for custom analyzers · MJML/Maizzle source-level linting · ESLint plugin · spam corpus tuning · dark-mode accuracy tests.
|
|
229
|
+
|
|
230
|
+
Concrete bugs go in [Issues](https://github.com/emailens/engine/issues). Open-ended ideas live in the roadmap.
|
|
231
|
+
|
|
232
|
+
## Contributing
|
|
233
|
+
|
|
234
|
+
Contributions are welcome! See **[CONTRIBUTING.md](./CONTRIBUTING.md)** for architecture overview, setup instructions, and PR guidelines.
|
|
235
|
+
|
|
236
|
+
```bash
|
|
237
|
+
bun install && bun test # 719 tests
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
Optional real-render validation: renders engine output in a real browser engine (free, no Litmus/Email on Acid needed). Off by default; needs a browser-capable machine:
|
|
241
|
+
|
|
242
|
+
```bash
|
|
243
|
+
bunx playwright install chromium
|
|
244
|
+
bun run test:render
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
### Data Maintenance
|
|
248
|
+
|
|
249
|
+
CSS support data is auto-synced from [caniemail.com](https://www.caniemail.com/). Other data (dark mode behavior, display limits, Superhuman overrides) is manually curated and tracked with verification dates.
|
|
250
|
+
|
|
251
|
+
```bash
|
|
252
|
+
bun run sync:caniemail # Refresh CSS support matrix from caniemail.com
|
|
253
|
+
bun run check:freshness # Flag stale data sources (exits 1 if any overdue)
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
See [CONTRIBUTING.md](./CONTRIBUTING.md#data-sources-and-freshness) for full details on data sources and verification procedures.
|
|
257
|
+
|
|
258
|
+
## License
|
|
259
|
+
|
|
260
|
+
MIT, Copyright 2025 [Emailens](https://emailens.dev)
|
|
261
|
+
|
|
262
|
+
---
|
|
263
|
+
|
|
264
|
+
If this saved you from an Outlook surprise, [a star](https://github.com/emailens/engine) helps other email developers find it.
|
package/dist/compile/index.d.cts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import {
|
|
2
|
-
export { C as CompileError, a as CompileReactEmailOptions, S as SandboxStrategy, c as compileReactEmail } from '../react-email-
|
|
1
|
+
import { Z as InputFormat } from '../types-edFeUest.cjs';
|
|
2
|
+
export { C as CompileError, a as CompileReactEmailOptions, S as SandboxStrategy, c as compileReactEmail } from '../react-email-DHkCZ7TG.cjs';
|
|
3
3
|
|
|
4
4
|
/**
|
|
5
5
|
* Compile an MJML source string into an HTML email string.
|
package/dist/compile/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import {
|
|
2
|
-
export { C as CompileError, a as CompileReactEmailOptions, S as SandboxStrategy, c as compileReactEmail } from '../react-email-
|
|
1
|
+
import { Z as InputFormat } from '../types-edFeUest.js';
|
|
2
|
+
export { C as CompileError, a as CompileReactEmailOptions, S as SandboxStrategy, c as compileReactEmail } from '../react-email-BzyXjPrH.js';
|
|
3
3
|
|
|
4
4
|
/**
|
|
5
5
|
* Compile an MJML source string into an HTML email string.
|