@emailens/cli 0.14.0 → 0.14.3

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 CHANGED
@@ -1,273 +1,300 @@
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 / cli" width="444">
6
- </picture>
7
-
8
- **The email rendering linter for terminal and CI**
9
-
10
- [![CI](https://github.com/emailens/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/emailens/cli/actions/workflows/ci.yml)
11
- [![npm](https://badgen.net/npm/v/@emailens/cli)](https://www.npmjs.com/package/@emailens/cli)
12
- [![MCP](https://badgen.net/badge/MCP/Server/blue)](https://github.com/emailens/mcp)
13
-
14
- </div>
15
-
16
- ```text
17
- $ emailens lint emails/welcome.html --fail-on-warning
18
- emails/welcome.html
19
- warn 7:10 outlook-windows-legacy display:flex Outlook Classic receives this flex box. The MSO branch needs a table.
20
- warn 7:25 outlook-windows-legacy,yahoo-mail,yahoo-mail-android+2 gap Outlook Classic does not support "gap".
21
- warn 8:32 gmail-web,outlook-windows-legacy,yahoo-mail-android+2 box-shadow Gmail does not support "box-shadow".
22
- warn 14:5 yahoo-mail font-family Yahoo Mail drops an inline font-family that names a quoted font, like 'Courier New': that text shows in Yahoo's own font instead.
23
- warn inboxPreview preheader-too-short Preheader is only 21 characters, so email clients may backfill with body text (recommended: 30+).
24
- 12 info: safe fallbacks, not problems. --info lists them.
25
-
26
- 1 file | 5 warnings
27
-
28
- Failed: 5 warnings found (--failOnWarning)
29
- See it rendered in Gmail, Outlook and Apple Mail, no signup: https://app.emailens.dev/try?utm_source=cli&utm_medium=lint
30
- ```
31
-
32
- That is a welcome email with a flex row and a card shadow, checked against 21
33
- email clients. Each finding has its line:column, and the exit code (here 2)
34
- fails the build. The card's rounded corners are among the 12 info findings:
35
- Outlook Classic draws them square, a safe fallback rather than a problem. The
36
- last line appears only when the check fails; `--quiet` drops it, and `--json`
37
- never has it.
38
-
39
- ## Install
40
-
41
- ```bash
42
- npm install -g @emailens/cli
43
- ```
44
-
45
- ## Run
46
-
47
- ```bash
48
- emailens lint 'emails/*.html'
49
- ```
50
-
51
- Or without installing: `npx @emailens/cli lint email.html`. HTML, React Email
52
- (`.tsx`/`.jsx`), MJML and Maizzle are detected from the extension and compiled
53
- first, so the check runs on the HTML that would be sent. No account and no
54
- network: the analysis runs locally.
55
-
56
- Exit codes: `0` clean, `1` errors, `2` warnings with `--fail-on-warning`, or
57
- more than `--max-warnings`.
58
-
59
- ### In a React Email project
60
-
61
- ```bash
62
- npx @emailens/cli react-email
63
- ```
64
-
65
- Finds the emails folder `email dev` uses (`emails/`, `src/emails/`), renders
66
- every template with your project's own React Email, `PreviewProps` included,
67
- and checks the HTML. Local imports, any npm package and tsconfig paths work,
68
- subfolders are included, and `_components`-style folders and files without a
69
- default export are skipped. No export step. `--watch` re-checks on save.
70
-
71
- Pass `--email-type transactional` (or set `"emailType": "transactional"` in
72
- `.emailensrc`) when the folder holds sign-in, receipt and alert emails, which
73
- need no unsubscribe link. `emailens lint emails/` does the same as the command
74
- above on a folder you name.
75
-
76
- ## Why not caniemail, or React Email's own checker?
77
-
78
- [Can I email](https://www.caniemail.com) is the support table: one feature,
79
- every client. It does not read your email. This CLI's support data is generated
80
- from caniemail's (synced 2026-10-27), plus the cells a real-device screenshot
81
- contradicted, each marked "Observed" with its date. What the CLI adds is the
82
- reading: it finds the features your file uses, points at the line, scores each
83
- client, and exits non-zero.
84
-
85
- [React Email 4](https://resend.com/blog/react-email-4) added a compatibility
86
- checker, also powered by Can I email, to its preview. Its CLI (`email dev`,
87
- `build`, `start`, `export`) has no check command and no exit code for CI, per
88
- [its docs](https://react.email/docs/cli). This CLI reads React Email files as
89
- well as MJML, Maizzle and plain HTML, and fails the build.
90
-
91
- Beyond CSS support, `lint` checks what neither covers: spam signals, links,
92
- accessibility, images, the inbox preview text, size, template variables,
93
- overflow, dark-mode and mobile contrast, Outlook VML, styles a client drops, and
94
- client-targeting hacks.
95
-
96
- ## Extras
97
-
98
- ### `lint` options
99
-
100
- | Flag | Alias | Description |
101
- |------|-------|-------------|
102
- | `--format` | `-f` | Input format: `html`, `jsx`, `mjml`, `maizzle`. `.vue` is `maizzle`. A pasted Vue file with no flag is detected. |
103
- | `--json` | | Output as JSON, one line, every finding including info |
104
- | `--info` | | List info findings too. By default they are counted, not listed: they are safe fallbacks, not problems |
105
- | `--fail-on-warning` | | Exit 2 if warnings found |
106
- | `--max-warnings` | | Fail if more than n warnings |
107
- | `--reporter github` | | Also print GitHub Actions annotations, so each finding shows on its line in the pull request. Not with `--json` |
108
- | `--quiet` | `-q` | No line about the hosted preview after a failure |
109
- | `--skip` | | Comma-separated checks to skip: `spam,links,accessibility,images,compatibility,inboxPreview,size,templateVariables,overflow,visual,darkContrast,mobileContrast,design,vml,styleSurvival,targeting` |
110
- | `--targeting-policy` | | `progressive` (default), `strict`, or `lenient` |
111
- | `--email-type` | | `transactional` drops the unsubscribe requirement; `marketing` keeps it. Default: `emailType` in `.emailensrc` |
112
- | `--gate` | | Also send each email to the hosted pre-send gate, which fails on a regression against the last version of that file that passed. Pro plan, needs `EMAILENS_API_KEY` |
113
-
114
- A `.emailensrc` in the project, the file the VS Code extension reads, can set
115
- rule severities and skips; `--skip` on the command line wins.
116
-
117
- Maizzle HTML needs `@maizzle/framework@5` installed beside the CLI. A `.vue`
118
- file needs `@maizzle/framework@6`. One install is one major.
119
-
120
- ### `emailens design`: does it still look like your design?
121
-
122
- `lint` reads the code. `design` reads the render: it draws the email as each
123
- client's live preview shows it and as you designed it, then compares the two
124
- layouts element by element. Every element is compared on its position, size,
125
- colours, corners, fonts and spacing. It gives the verdict the Emailens email
126
- page shows: **Ready**, **Needs work** or **Broken**, with the reasons.
127
-
128
- ```text
129
- $ emailens design emails/welcome.html --clients outlook-windows-legacy,gmail-web
130
- ✗ Outlook Classic Broken
131
- Outlook Classic breaks your design.
132
- - Columns that sit side by side in your design stack on top of each other.
133
- - The email is drawn at a very different width from your design (54% of it).
134
- - “Track your parcel” is moved (centre at 25% → 50% across the email) and 1107px wide instead of 300px.
135
- - “Manage your order” is moved (centre at 75% → 50% across the email) and 1107px wide instead of 300px.
136
- - Layout differs in 4 places. For example, “Hello, your order has shipped.” has width 600px instead of 552px.
137
- and 1 more
138
- ✓ Gmail Ready
139
- ```
140
-
141
- That email puts two buttons side by side with `display:flex`. Classic Outlook
142
- has no flexbox, so the buttons stack at full width. Gmail sets its own line
143
- height and text colour, but the screenshots of the two pages differ by under
144
- 2.5% of their pixels, so the design reads as kept.
145
-
146
- Layout needs a browser, so this command needs one too. `sharp` adds the pixel
147
- comparison:
148
-
149
- ```bash
150
- npm install -g @emailens/cli playwright-core sharp
151
- npx playwright-core install chromium # a local Chromium, or:
152
- export BROWSERLESS_URL=wss://... # your Browserless instance
153
- emailens design email.html
154
- ```
155
-
156
- Or without installing: `npx -p @emailens/cli -p playwright-core -p sharp emailens design email.html`.
157
-
158
- | Flag | Alias | Description |
159
- |------|-------|-------------|
160
- | `--clients` | `-c` | Comma-separated client IDs. Default: all 21 |
161
- | `--format` | `-f` | Input format: `html`, `jsx`, `mjml`, `maizzle` |
162
- | `--strict` | | Fail on Needs work too, not only on Broken |
163
- | `--json` | | Output as JSON |
164
- | `--quiet` | `-q` | No spinner |
165
-
166
- Exit codes: `0` when no client breaks the design, `1` when one does (or, with
167
- `--strict`, when one changes it).
168
-
169
- **What it covers and what it doesn't:**
170
- - It runs in light mode, against our live preview of each client. It doesn't
171
- screenshot real inboxes: real-device screenshots are on the hosted plans.
172
- - With `sharp` installed, it also screenshots both pages and compares them
173
- pixel by pixel, as the hosted check on saved emails does. That agrees more
174
- often with a human reviewer. Without `sharp`, it compares page structure
175
- only, as the email page in your browser does, and the JSON has no `diff`.
176
- - On Browserless, the session has to stay open for the whole run. A short
177
- session timeout closes the browser midway: raise its `TIMEOUT`, or pass
178
- fewer `--clients`.
179
- - Scripts are off in both pages. The email's own images and fonts load from
180
- their addresses.
181
- - The font stand-ins the previews use (Segoe, Aptos, the Apple and Android
182
- system fonts) are downloaded once from app.emailens.dev into
183
- `~/.cache/emailens/fonts`.
184
-
185
- ### Other commands
186
-
187
- ```bash
188
- emailens analyze email.html # score per client, findings by client
189
- emailens analyze email.html --clients gmail-web,outlook-windows --json
190
- emailens audit email.html # compatibility plus every other check
191
- emailens preview email.html --dark-mode # transforms, analysis, dark mode simulation
192
- emailens preview email.html --screenshots --out ./shots # needs BROWSERLESS_URL and playwright-core
193
- emailens design email.html --clients gmail-web # still looks like the design? needs playwright-core (+ sharp)
194
- emailens export email.html -o ./report # self-contained HTML report (--json for JSON)
195
- emailens fix email.html -o fixed.html # AI fix, needs ANTHROPIC_API_KEY (--estimate: tokens only)
196
- emailens clients # the 21 clients
197
- cat email.html | emailens analyze - # stdin
198
- ```
199
-
200
- ### `emailens inbox wait`
201
-
202
- The CI step for what your app actually sends. Make your app send a real email
203
- (sign-up, reset, receipt) to your Emailens test inbox, then wait for it. It
204
- fails when the email is no longer the one you checked in Emailens, or changed
205
- since it last arrived: a link moved to staging, an emptied variable, a new
206
- line, an image gone, a size jump, signing that stopped passing. Codes, tokens
207
- and tracking ids differ on every send and do not count. It needs an API key.
208
-
209
- ```bash
210
- export EMAILENS_API_KEY=... # app.emailens.dev/dashboard/api
211
- SINCE=$(date +%s000) # before the send
212
- npm run send-signup-email # your app sends it
213
- emailens inbox wait --subject "Welcome" --since "$SINCE"
214
- ```
215
-
216
- Options: `--subject`, `--sender`, `--inbox <id>`, `--since` (ISO time, epoch
217
- ms, or a duration such as `5m`; default 2 minutes back), `--timeout` (seconds,
218
- default 60, at most 600), `--fail-on all|check|drift|none` (default `all`),
219
- `--json`. Exit codes: `0` pass, `1` changed, `2` nothing arrived or Emailens
220
- could not be reached.
221
-
222
- ### In your tests
223
-
224
- The same check as `lint`, as an assertion. It throws with every failing
225
- finding and its line, reads your `.emailensrc`, and works in Vitest, Jest and
226
- bun:test.
227
-
228
- ```ts
229
- import { render } from "@react-email/render";
230
- import { expectEmailToPass } from "@emailens/cli/test";
231
-
232
- test("welcome email passes", async () => {
233
- expectEmailToPass(await render(<Welcome name="Ada" />));
234
- });
235
- ```
236
-
237
- Options: `failOnWarning`, `skip` (the `--skip` names), `framework`.
238
-
239
- ### In GitHub Actions
240
-
241
- ```yaml
242
- - uses: actions/setup-node@v4
243
- with:
244
- node-version: 22
245
- - run: npx -y @emailens/cli lint 'emails/*.html' --fail-on-warning --reporter github
246
- ```
247
-
248
- `--reporter github` puts each finding on its line in the pull request's
249
- changed files.
250
-
251
- `**` globs are not supported: use a single-level wildcard or list the files.
252
- For scores per client in a pull request comment, use the
253
- [Action](https://github.com/emailens/action).
254
-
255
- ### Hosted
256
-
257
- [app.emailens.dev/try](https://app.emailens.dev/try?utm_source=cli&utm_medium=readme)
258
- renders the email per client: five clients with no account, all 21 with a free
259
- one. The + Real plans add real-device screenshots: Outlook on Windows and Mac,
260
- Apple Mail on Mac and iPad, and Gmail, Yahoo and Proton on the web.
261
-
262
- ## Ecosystem
263
-
264
- | Project | What it is |
265
- |---|---|
266
- | [@emailens/engine](https://github.com/emailens/engine) | The analysis engine this CLI runs, as a library |
267
- | [@emailens/mcp](https://github.com/emailens/mcp) | The same checks for coding agents: `claude mcp add emailens -- npx -y @emailens/mcp` |
268
- | [emailens/action](https://github.com/emailens/action) | GitHub Action: fails the build, and can comment the scores per client on the pull request |
269
- | [emailens/vscode](https://github.com/emailens/vscode) | VS Code extension: findings and preview in the editor |
270
-
271
- ## License
272
-
273
- MIT
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 / cli" width="444">
6
+ </picture>
7
+
8
+ **The email rendering linter for terminal and CI**
9
+
10
+ [![CI](https://github.com/emailens/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/emailens/cli/actions/workflows/ci.yml)
11
+ [![npm](https://badgen.net/npm/v/@emailens/cli)](https://www.npmjs.com/package/@emailens/cli)
12
+ [![MCP](https://badgen.net/badge/MCP/Server/blue)](https://github.com/emailens/mcp)
13
+
14
+ </div>
15
+
16
+ ```text
17
+ $ emailens lint emails/welcome.html --fail-on-warning
18
+ emails/welcome.html
19
+ warn 7:10 outlook-windows-legacy display:flex Outlook Classic receives this flex box. The MSO branch needs a table.
20
+ warn 7:25 outlook-windows-legacy,yahoo-mail,yahoo-mail-android+2 gap Outlook Classic does not support "gap".
21
+ warn 8:32 gmail-web,outlook-windows-legacy,yahoo-mail-android+2 box-shadow Gmail does not support "box-shadow".
22
+ warn 14:5 yahoo-mail font-family Yahoo Mail drops an inline font-family that names a quoted font, like 'Courier New': that text shows in Yahoo's own font instead.
23
+ warn inboxPreview preheader-too-short Preheader is only 21 characters, so email clients may backfill with body text (recommended: 30+).
24
+ 12 info: safe fallbacks, not problems. --info lists them.
25
+
26
+ 1 file | 5 warnings
27
+
28
+ Failed: 5 warnings found (--failOnWarning)
29
+ See it rendered in Gmail, Outlook and Apple Mail, no signup: https://app.emailens.dev/try?utm_source=cli&utm_medium=lint
30
+ ```
31
+
32
+ That is a welcome email with a flex row and a card shadow, checked against 21
33
+ email clients. Each finding has its line:column, and the exit code (here 2)
34
+ fails the build. The card's rounded corners are among the 12 info findings:
35
+ Outlook Classic draws them square, a safe fallback rather than a problem. The
36
+ last line appears only when the check fails; `--quiet` drops it, and `--json`
37
+ never has it.
38
+
39
+ ## Install
40
+
41
+ ```bash
42
+ npm install -g @emailens/cli
43
+ ```
44
+
45
+ ## Run
46
+
47
+ ```bash
48
+ emailens lint 'emails/*.html'
49
+ ```
50
+
51
+ Or without installing: `npx @emailens/cli lint email.html`. HTML, React Email
52
+ (`.tsx`/`.jsx`), MJML and Maizzle are detected from the extension and compiled
53
+ first, so the check runs on the HTML that would be sent. No account and no
54
+ network: the analysis runs locally.
55
+
56
+ Exit codes: `0` clean, `1` errors, `2` warnings with `--fail-on-warning`, or
57
+ more than `--max-warnings`.
58
+
59
+ ### In a React Email project
60
+
61
+ ```bash
62
+ npx @emailens/cli react-email
63
+ ```
64
+
65
+ Finds the emails folder `email dev` uses (`emails/`, `src/emails/`), renders
66
+ every template with your project's own React Email, `PreviewProps` included,
67
+ and checks the HTML. Local imports, any npm package and tsconfig paths work,
68
+ subfolders are included, and `_components`-style folders and files without a
69
+ default export are skipped. No export step. `--watch` re-checks on save.
70
+
71
+ Pass `--email-type transactional` (or set `"emailType": "transactional"` in
72
+ `.emailensrc`) when the folder holds sign-in, receipt and alert emails, which
73
+ need no unsubscribe link. `emailens lint emails/` does the same as the command
74
+ above on a folder you name.
75
+
76
+ ## Why not caniemail, or React Email's own checker?
77
+
78
+ [Can I email](https://www.caniemail.com) is the support table: one feature,
79
+ every client. It does not read your email. This CLI's support data is generated
80
+ from caniemail's (synced 2026-10-27), plus the cells a real-device screenshot
81
+ contradicted, each marked "Observed" with its date. What the CLI adds is the
82
+ reading: it finds the features your file uses, points at the line, scores each
83
+ client, and exits non-zero.
84
+
85
+ [React Email 4](https://resend.com/blog/react-email-4) added a compatibility
86
+ checker, also powered by Can I email, to its preview. Its CLI (`email dev`,
87
+ `build`, `start`, `export`) has no check command and no exit code for CI, per
88
+ [its docs](https://react.email/docs/cli). This CLI reads React Email files as
89
+ well as MJML, Maizzle and plain HTML, and fails the build.
90
+
91
+ Beyond CSS support, `lint` checks what neither covers: spam signals, links,
92
+ accessibility, images, the inbox preview text, size, template variables,
93
+ overflow, dark-mode and mobile contrast, Outlook VML, styles a client drops, and
94
+ client-targeting hacks.
95
+
96
+ ## Extras
97
+
98
+ ### `lint` options
99
+
100
+ | Flag | Alias | Description |
101
+ |------|-------|-------------|
102
+ | `--format` | `-f` | Input format: `html`, `jsx`, `mjml`, `maizzle`. `.vue` is `maizzle`. A pasted Vue file with no flag is detected. |
103
+ | `--json` | | Output as JSON, one line, every finding including info |
104
+ | `--info` | | List info findings too. By default they are counted, not listed: they are safe fallbacks, not problems |
105
+ | `--fail-on-warning` | | Exit 2 if warnings found |
106
+ | `--max-warnings` | | Fail if more than n warnings |
107
+ | `--reporter github` | | Also print GitHub Actions annotations, so each finding shows on its line in the pull request. Not with `--json` |
108
+ | `--quiet` | `-q` | No line about the hosted preview after a failure |
109
+ | `--skip` | | Comma-separated checks to skip: `spam,links,accessibility,images,compatibility,inboxPreview,size,templateVariables,overflow,visual,darkContrast,mobileContrast,design,vml,styleSurvival,targeting` |
110
+ | `--targeting-policy` | | `progressive` (default), `strict`, or `lenient` |
111
+ | `--email-type` | | `transactional` drops the unsubscribe requirement; `marketing` keeps it. Default: `emailType` in `.emailensrc` |
112
+ | `--gate` | | Also send each email to the hosted pre-send gate, which fails on a regression against the last version of that file that passed. Pro plan, needs `EMAILENS_API_KEY` |
113
+
114
+ A `.emailensrc` in the project, the file the VS Code extension reads, can set
115
+ rule severities and skips; `--skip` on the command line wins.
116
+
117
+ Maizzle HTML needs `@maizzle/framework@5` installed beside the CLI. A `.vue`
118
+ file needs `@maizzle/framework@6`. One install is one major.
119
+
120
+ ### `emailens design`: does it still look like your design?
121
+
122
+ `lint` reads the code. `design` reads the render: it draws the email as each
123
+ client's live preview shows it and as you designed it, then compares the two
124
+ layouts element by element. Every element is compared on its position, size,
125
+ colours, corners, fonts and spacing. It gives the verdict the Emailens email
126
+ page shows: **Ready**, **Needs work** or **Broken**, with the reasons.
127
+
128
+ ```text
129
+ $ emailens design emails/welcome.html --clients outlook-windows-legacy,gmail-web
130
+ ✗ Outlook Classic Broken
131
+ Outlook Classic breaks your design.
132
+ - Columns that sit side by side in your design stack on top of each other.
133
+ - The email is drawn at a very different width from your design (54% of it).
134
+ - “Track your parcel” is moved (centre at 25% → 50% across the email) and 1107px wide instead of 300px.
135
+ - “Manage your order” is moved (centre at 75% → 50% across the email) and 1107px wide instead of 300px.
136
+ - Layout differs in 4 places. For example, “Hello, your order has shipped.” has width 600px instead of 552px.
137
+ and 1 more
138
+ ✓ Gmail Ready
139
+ ```
140
+
141
+ That email puts two buttons side by side with `display:flex`. Classic Outlook
142
+ has no flexbox, so the buttons stack at full width. Gmail sets its own line
143
+ height and text colour, but the screenshots of the two pages differ by under
144
+ 2.5% of their pixels, so the design reads as kept.
145
+
146
+ Layout needs a browser, so this command needs one too. `sharp` adds the pixel
147
+ comparison:
148
+
149
+ ```bash
150
+ npm install -g @emailens/cli playwright-core sharp
151
+ npx playwright-core install chromium # a local Chromium, or:
152
+ export BROWSERLESS_URL=wss://... # your Browserless instance
153
+ emailens design email.html
154
+ ```
155
+
156
+ Or without installing: `npx -p @emailens/cli -p playwright-core -p sharp emailens design email.html`.
157
+
158
+ | Flag | Alias | Description |
159
+ |------|-------|-------------|
160
+ | `--clients` | `-c` | Comma-separated client IDs. Default: all 21 |
161
+ | `--format` | `-f` | Input format: `html`, `jsx`, `mjml`, `maizzle` |
162
+ | `--strict` | | Fail on Needs work too, not only on Broken |
163
+ | `--json` | | Output as JSON |
164
+ | `--quiet` | `-q` | No spinner |
165
+
166
+ Exit codes: `0` when no client breaks the design, `1` when one does (or, with
167
+ `--strict`, when one changes it).
168
+
169
+ **What it covers and what it doesn't:**
170
+ - It runs in light mode, against our live preview of each client. It doesn't
171
+ screenshot real inboxes: real-device screenshots are on the hosted plans.
172
+ - With `sharp` installed, it also screenshots both pages and compares them
173
+ pixel by pixel, as the hosted check on saved emails does. That agrees more
174
+ often with a human reviewer. Without `sharp`, it compares page structure
175
+ only, as the email page in your browser does, and the JSON has no `diff`.
176
+ - On Browserless, the session has to stay open for the whole run. A short
177
+ session timeout closes the browser midway: raise its `TIMEOUT`, or pass
178
+ fewer `--clients`.
179
+ - Scripts are off in both pages. The email's own images and fonts load from
180
+ their addresses.
181
+ - Both pages draw with the same font stand-ins (Arimo for Arial and
182
+ Helvetica, and faces for Segoe, Aptos and the Apple and Android system
183
+ fonts), so the verdict is the same on a Mac, on Windows and on a bare Linux
184
+ runner. They are downloaded once from app.emailens.dev into
185
+ `~/.cache/emailens/fonts`. If that fails, the command says so on stderr:
186
+ text then draws in this machine's fonts and can read as a change.
187
+
188
+ ### Other commands
189
+
190
+ ```bash
191
+ emailens analyze email.html # score per client, findings by client
192
+ emailens analyze email.html --clients gmail-web,outlook-windows --json
193
+ emailens audit email.html # compatibility plus every other check
194
+ emailens preview email.html --dark-mode # transforms, analysis, dark mode simulation
195
+ emailens preview email.html --screenshots --out ./shots # needs BROWSERLESS_URL and playwright-core
196
+ emailens design email.html --clients gmail-web # still looks like the design? needs playwright-core (+ sharp)
197
+ emailens export email.html -o ./report # self-contained HTML report (--json for JSON)
198
+ emailens fix email.html -o fixed.html # AI fix, needs ANTHROPIC_API_KEY (--estimate: tokens only)
199
+ emailens clients # the 21 clients
200
+ cat email.html | emailens analyze - # stdin
201
+ ```
202
+
203
+ ### `emailens inbox wait`
204
+
205
+ The CI step for what your app actually sends. Make your app send a real email
206
+ (sign-up, reset, receipt) to your Emailens test inbox, then wait for it. It
207
+ fails when the email is no longer the one you checked in Emailens, or changed
208
+ since it last arrived: a link moved to staging, an emptied variable, a new
209
+ line, an image gone, a size jump, signing that stopped passing. Codes, tokens
210
+ and tracking ids differ on every send and do not count. It needs an API key.
211
+
212
+ ```bash
213
+ export EMAILENS_API_KEY=... # app.emailens.dev/dashboard/api
214
+ SINCE=$(date +%s000) # before the send
215
+ npm run send-signup-email # your app sends it
216
+ emailens inbox wait --subject "Welcome" --since "$SINCE"
217
+ ```
218
+
219
+ For release history against a named approved preview, create a saved test in
220
+ the Emailens dashboard, then begin the run before the staging send. The run ID
221
+ ties delayed delivery to that release and stores branch and commit metadata:
222
+
223
+ ```bash
224
+ RUN=$(emailens inbox begin YOUR_SAVED_TEST_ID --json)
225
+ RUN_ID=$(node -p 'JSON.parse(process.argv[1]).runId' "$RUN")
226
+ npm run send-signup-email
227
+ emailens inbox wait --test YOUR_SAVED_TEST_ID --run-id "$RUN_ID" --timeout 180
228
+ ```
229
+
230
+ The saved test controls its inbox, subject, sender, approved preview, and
231
+ failure policy. `inbox wait` still supports the untracked `--subject` and
232
+ `--since` flow shown above.
233
+
234
+ Options: `--subject`, `--sender`, `--inbox <id>`, `--since` (ISO time, epoch
235
+ ms, or a duration such as `5m`; default 2 minutes back), `--timeout` (seconds,
236
+ default 60, at most 600), `--fail-on all|check|drift|none` (default `all`),
237
+ `--json`. Exit codes: `0` pass, `1` changed, `2` nothing arrived or Emailens
238
+ could not be reached.
239
+
240
+ ### In your tests
241
+
242
+ The same check as `lint`, as an assertion. It throws with every failing
243
+ finding and its line, reads your `.emailensrc`, and works in Vitest, Jest and
244
+ bun:test.
245
+
246
+ ```ts
247
+ import { render } from "@react-email/render";
248
+ import { expectEmailToPass } from "@emailens/cli/test";
249
+
250
+ test("welcome email passes", async () => {
251
+ expectEmailToPass(await render(<Welcome name="Ada" />));
252
+ });
253
+ ```
254
+
255
+ Options: `failOnWarning`, `skip` (the `--skip` names), `framework`.
256
+
257
+ ### In GitHub Actions
258
+
259
+ ```yaml
260
+ - uses: actions/setup-node@v4
261
+ with:
262
+ node-version: 22
263
+ - run: npx -y @emailens/cli lint 'emails/*.html' --fail-on-warning --reporter github
264
+ ```
265
+
266
+ `--reporter github` puts each finding on its line in the pull request's
267
+ changed files.
268
+
269
+ To fail the build when a client breaks the design, add `design`. It needs a
270
+ Chromium on the runner:
271
+
272
+ ```yaml
273
+ - run: npm install -g @emailens/cli playwright-core sharp
274
+ - run: npx playwright-core install --with-deps chromium
275
+ - run: emailens design emails/welcome.html --clients outlook-windows-legacy,gmail-web,apple-mail-macos
276
+ ```
277
+
278
+ `**` globs are not supported: use a single-level wildcard or list the files.
279
+ For scores per client in a pull request comment, use the
280
+ [Action](https://github.com/emailens/action).
281
+
282
+ ### Hosted
283
+
284
+ [app.emailens.dev/try](https://app.emailens.dev/try?utm_source=cli&utm_medium=readme)
285
+ renders the email per client: five clients with no account, all 21 with a free
286
+ one. The + Real plans add real-device screenshots: Outlook on Windows and Mac,
287
+ Apple Mail on Mac and iPad, and Gmail, Yahoo and Proton on the web.
288
+
289
+ ## Ecosystem
290
+
291
+ | Project | What it is |
292
+ |---|---|
293
+ | [@emailens/engine](https://github.com/emailens/engine) | The analysis engine this CLI runs, as a library |
294
+ | [@emailens/mcp](https://github.com/emailens/mcp) | The same checks for coding agents: `claude mcp add emailens -- npx -y @emailens/mcp` |
295
+ | [emailens/action](https://github.com/emailens/action) | GitHub Action: fails the build, and can comment the scores per client on the pull request |
296
+ | [emailens/vscode](https://github.com/emailens/vscode) | VS Code extension: findings and preview in the editor |
297
+
298
+ ## License
299
+
300
+ MIT
@@ -726,8 +726,10 @@ function measureGap(pane, real) {
726
726
  range(fine.scale - 25e-4, fine.scale + 25e-4, 125e-5),
727
727
  { x: fine.x, y: fine.y, r: 2 }
728
728
  );
729
- const x = Math.round(full.x - left2 * full.scale);
730
- return __spreadValues(__spreadProps(__spreadValues({}, full), { x }), compare(sim, real, full));
729
+ const one = search(sim, real, 1, [1], { x: full.x, y: full.y, r: 3 });
730
+ const best = one.match > full.match ? one : full;
731
+ const x = Math.round(best.x - left2 * best.scale);
732
+ return __spreadValues(__spreadProps(__spreadValues({}, best), { x }), compare(sim, real, best));
731
733
  }
732
734
  var CLIENT_VIEWPORTS = {
733
735
  // Desktop web clients , all at 2x for consistent quality.
@@ -1935,7 +1937,7 @@ function designDoc(html, client, frameWidth) {
1935
1937
  const fits = /\.emailens-shell img\{/.test(shellStyle);
1936
1938
  const doc = injectStyleIntoHtml(
1937
1939
  html,
1938
- `<style>html,body{margin:0!important}:root{box-sizing:border-box!important;width:${frameWidth}px!important;padding:0 ${gutter}!important}${fits ? "img{max-width:100%;height:auto}" : ""}</style>`
1940
+ `<style>${FONT_FACE_STYLE}html,body{margin:0!important}:root{box-sizing:border-box!important;width:${frameWidth}px!important;padding:0 ${gutter}!important}${fits ? "img{max-width:100%;height:auto}" : ""}</style>`
1939
1941
  );
1940
1942
  return { doc, fits };
1941
1943
  }
@@ -2031,11 +2033,19 @@ Set BROWSERLESS_URL to a Browserless instance, or install one: npx playwright-co
2031
2033
  })
2032
2034
  ]).finally(() => clearTimeout(timer));
2033
2035
  }
2036
+ var fontWarned = false;
2034
2037
  async function font(name) {
2035
2038
  const file = join(FONT_CACHE, name);
2036
2039
  if (existsSync(file)) return readFileSync(file);
2037
2040
  const res = await fetch(FONTS_FROM + name).catch(() => null);
2038
- if (!(res == null ? void 0 : res.ok)) return null;
2041
+ if (!(res == null ? void 0 : res.ok)) {
2042
+ if (!fontWarned)
2043
+ console.warn(
2044
+ `emailens design: could not fetch the stand-in fonts from ${FONTS_FROM} (${res ? `HTTP ${res.status}` : "no connection"}). Text is drawn in this machine's own fonts, so verdicts may read changes that are not there.`
2045
+ );
2046
+ fontWarned = true;
2047
+ return null;
2048
+ }
2039
2049
  const body = Buffer.from(await res.arrayBuffer());
2040
2050
  mkdirSync(FONT_CACHE, { recursive: true });
2041
2051
  writeFileSync(file, body);
package/dist/index.js CHANGED
@@ -43706,7 +43706,7 @@ Href: ${href}`
43706
43706
  // package.json
43707
43707
  var package_default = {
43708
43708
  name: "@emailens/cli",
43709
- version: "0.14.0",
43709
+ version: "0.14.3",
43710
43710
  description: "CLI tool for email compatibility analysis: lint, preview and export HTML, MJML, Maizzle and React Email rendering across 21 email clients.",
43711
43711
  type: "module",
43712
43712
  bin: {
@@ -43751,7 +43751,7 @@ var package_default = {
43751
43751
  },
43752
43752
  devDependencies: {
43753
43753
  "@anthropic-ai/sdk": "^0.52.0",
43754
- "@emailens/engine": "^0.19.0",
43754
+ "@emailens/engine": "^0.19.1",
43755
43755
  "@react-email/components": "1.0.12",
43756
43756
  "@types/bun": "^1.4.0",
43757
43757
  "@types/mjml": "^4.7.4",
@@ -46194,6 +46194,7 @@ function printQualitySummary(report, skip, options) {
46194
46194
  // src/commands/inbox.ts
46195
46195
  var import_picocolors5 = __toESM(require_picocolors(), 1);
46196
46196
  var API_URL = () => process.env.EMAILENS_API_URL ?? "https://app.emailens.dev";
46197
+ var SERVER_WAIT_SECONDS = 20;
46197
46198
  function parseSince(value, now = Date.now()) {
46198
46199
  if (!value) return now - 2 * 6e4;
46199
46200
  const d = /^(\d+)\s*(s|m|h)$/i.exec(value.trim());
@@ -46208,11 +46209,21 @@ async function waitForEmail(o, fetchImpl = fetch) {
46208
46209
  while (Date.now() < deadline) {
46209
46210
  const q = new URLSearchParams({
46210
46211
  since: String(o.since),
46211
- timeout: String(Math.max(1, Math.min(60, Math.ceil((deadline - Date.now()) / 1e3))))
46212
+ timeout: String(
46213
+ Math.max(
46214
+ 1,
46215
+ Math.min(
46216
+ SERVER_WAIT_SECONDS,
46217
+ Math.ceil((deadline - Date.now()) / 1e3)
46218
+ )
46219
+ )
46220
+ )
46212
46221
  });
46213
46222
  if (o.subject) q.set("subject", o.subject);
46214
46223
  if (o.sender) q.set("sender", o.sender);
46215
46224
  if (o.inbox) q.set("inboxId", o.inbox);
46225
+ if (o.testId) q.set("testId", o.testId);
46226
+ if (o.runId) q.set("runId", o.runId);
46216
46227
  let res;
46217
46228
  try {
46218
46229
  res = await fetchImpl(`${API_URL()}/api/sandbox/v1/messages/wait?${q}`, {
@@ -46221,21 +46232,80 @@ async function waitForEmail(o, fetchImpl = fetch) {
46221
46232
  } catch (e) {
46222
46233
  return { code: 2, error: `Could not reach Emailens: ${e.message}`, failures: [] };
46223
46234
  }
46224
- if (res.status === 408) continue;
46235
+ if ([408, 502, 503, 504].includes(res.status)) continue;
46225
46236
  const body = await res.json().catch(() => ({}));
46226
46237
  if (res.status === 401)
46227
46238
  return { code: 2, error: "Invalid or revoked API key (EMAILENS_API_KEY).", failures: [] };
46228
- if (!res.ok) return { code: 2, error: body.error ?? `Emailens answered ${res.status}.`, failures: [] };
46239
+ if (!res.ok) {
46240
+ if (body.ambiguous && o.testId && o.runId)
46241
+ return { code: 1, response: body, error: body.error, failures: [body.error ?? "More than one matching email arrived."] };
46242
+ return { code: 2, error: body.error ?? `Emailens answered ${res.status}.`, failures: [] };
46243
+ }
46229
46244
  const a = body.message?.analysis ?? {};
46230
46245
  const bad = (rows) => (rows ?? []).filter((r) => !r.ok).map((r) => r.text);
46231
- const failures = [
46246
+ const failures = o.testId && body.verdict ? body.verdict.reasons : [
46232
46247
  ...o.failOn === "all" || o.failOn === "check" ? bad(a.match?.rows) : [],
46233
46248
  ...o.failOn === "all" || o.failOn === "drift" ? bad(a.drift?.rows) : []
46234
46249
  ];
46235
- return { code: failures.length ? 1 : 0, response: body, failures };
46250
+ return { code: o.testId && body.verdict ? body.verdict.pass ? 0 : 1 : failures.length ? 1 : 0, response: body, failures };
46251
+ }
46252
+ const error = `No matching email arrived within ${o.timeout}s.`;
46253
+ if (o.testId && o.runId) {
46254
+ try {
46255
+ await fetchImpl(`${API_URL()}/api/email-tests/${encodeURIComponent(o.testId)}/runs/${encodeURIComponent(o.runId)}`, {
46256
+ method: "PATCH",
46257
+ headers: { Authorization: `Bearer ${o.apiKey}`, "Content-Type": "application/json" },
46258
+ body: JSON.stringify({ status: "timed_out", reasons: [error] })
46259
+ });
46260
+ } catch {
46261
+ }
46236
46262
  }
46237
- return { code: 2, error: `No matching email arrived within ${o.timeout}s.`, failures: [] };
46263
+ return { code: 2, error, failures: [] };
46238
46264
  }
46265
+ var begin = defineCommand({
46266
+ meta: { name: "begin", description: "Start a saved email test run before your app sends the staging email" },
46267
+ args: {
46268
+ testId: { type: "positional", required: true, description: "Saved email test ID" },
46269
+ "api-key": { type: "string", description: "API key (default: EMAILENS_API_KEY)" },
46270
+ json: { type: "boolean", description: "Output run metadata as JSON" }
46271
+ },
46272
+ async run({ args }) {
46273
+ const apiKey = args["api-key"] ?? process.env.EMAILENS_API_KEY;
46274
+ const testId = args.testId;
46275
+ if (!apiKey || !testId) {
46276
+ console.error(import_picocolors5.default.red(" Usage: emailens inbox begin <test-id> (set EMAILENS_API_KEY)."));
46277
+ process.exitCode = 2;
46278
+ return;
46279
+ }
46280
+ const metadata = {
46281
+ source: process.env.GITHUB_ACTIONS ? "github-action" : "cli",
46282
+ commitSha: process.env.GITHUB_SHA ?? process.env.GIT_COMMIT,
46283
+ branch: process.env.GITHUB_REF_NAME ?? process.env.GIT_BRANCH,
46284
+ environment: process.env.GITHUB_ENVIRONMENT ?? process.env.DEPLOY_ENVIRONMENT
46285
+ };
46286
+ let response;
46287
+ try {
46288
+ response = await fetch(`${API_URL()}/api/email-tests/${encodeURIComponent(testId)}/runs`, {
46289
+ method: "POST",
46290
+ headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
46291
+ body: JSON.stringify(metadata)
46292
+ });
46293
+ } catch (e) {
46294
+ console.error(import_picocolors5.default.red(` Could not reach Emailens: ${e.message}`));
46295
+ process.exitCode = 2;
46296
+ return;
46297
+ }
46298
+ const body = await response.json().catch(() => ({}));
46299
+ if (!response.ok || !body.run) {
46300
+ console.error(import_picocolors5.default.red(` ${body.error ?? `Emailens answered ${response.status}.`}`));
46301
+ process.exitCode = response.status === 401 ? 2 : 1;
46302
+ return;
46303
+ }
46304
+ const result = { testId, runId: body.run.id, startedAt: body.run.startedAt };
46305
+ if (args.json) console.log(JSON.stringify(result));
46306
+ else console.log(` Started email test run ${result.runId}`);
46307
+ }
46308
+ });
46239
46309
  var wait = defineCommand({
46240
46310
  meta: {
46241
46311
  name: "wait",
@@ -46256,6 +46326,8 @@ var wait = defineCommand({
46256
46326
  default: "all"
46257
46327
  },
46258
46328
  "api-key": { type: "string", description: "API key (default: EMAILENS_API_KEY)" },
46329
+ test: { type: "string", description: "Saved test ID; pair with --run-id" },
46330
+ "run-id": { type: "string", description: "Run ID returned by inbox begin" },
46259
46331
  json: { type: "boolean", description: "Output as JSON" }
46260
46332
  },
46261
46333
  async run({ args }) {
@@ -46265,6 +46337,10 @@ var wait = defineCommand({
46265
46337
  console.error(import_picocolors5.default.red(" Set EMAILENS_API_KEY (or pass --api-key). Keys are at app.emailens.dev/dashboard/api."));
46266
46338
  process.exit(2);
46267
46339
  }
46340
+ if (Boolean(args.test) !== Boolean(args["run-id"])) {
46341
+ console.error(import_picocolors5.default.red(" --test and --run-id must be provided together."));
46342
+ process.exit(2);
46343
+ }
46268
46344
  if (!["all", "check", "drift", "none"].includes(failOn)) {
46269
46345
  console.error(import_picocolors5.default.red(` --fail-on: all, check, drift or none, not ${failOn}.`));
46270
46346
  process.exit(2);
@@ -46283,7 +46359,9 @@ var wait = defineCommand({
46283
46359
  inbox: args.inbox,
46284
46360
  since,
46285
46361
  timeout: Math.min(600, Math.max(1, Number(args.timeout) || 60)),
46286
- failOn
46362
+ failOn,
46363
+ testId: args.test,
46364
+ runId: args["run-id"]
46287
46365
  });
46288
46366
  if (args.json) {
46289
46367
  console.log(
@@ -46338,7 +46416,7 @@ var inbox_default = defineCommand({
46338
46416
  name: "inbox",
46339
46417
  description: "Your Emailens test inbox, from CI"
46340
46418
  },
46341
- subCommands: { wait }
46419
+ subCommands: { begin, wait }
46342
46420
  });
46343
46421
 
46344
46422
  // src/commands/react-email.ts
@@ -46444,7 +46522,7 @@ var design_default = defineCommand({
46444
46522
  const format = resolveFormat(args.format, args.input, source);
46445
46523
  const html = await compile(source, format);
46446
46524
  const clientIds = resolveClients(args.clients);
46447
- const { checkDesignAcross } = await import("./design-3W7LDIBV.js");
46525
+ const { checkDesignAcross } = await import("./design-AAMRTVQO.js");
46448
46526
  spinner?.start(process.env.BROWSERLESS_URL ? "Connecting to Browserless..." : "Starting Chromium...");
46449
46527
  const results = await checkDesignAcross(html, clientIds, {
46450
46528
  framework: toFramework(format),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@emailens/cli",
3
- "version": "0.14.0",
3
+ "version": "0.14.3",
4
4
  "description": "CLI tool for email compatibility analysis: lint, preview and export HTML, MJML, Maizzle and React Email rendering across 21 email clients.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -45,7 +45,7 @@
45
45
  },
46
46
  "devDependencies": {
47
47
  "@anthropic-ai/sdk": "^0.52.0",
48
- "@emailens/engine": "^0.19.0",
48
+ "@emailens/engine": "^0.19.1",
49
49
  "@react-email/components": "1.0.12",
50
50
  "@types/bun": "^1.4.0",
51
51
  "@types/mjml": "^4.7.4",