@emailens/mcp 0.14.0 → 0.16.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 +392 -336
- package/dist/index.js +62 -1
- package/dist/index.js.map +1 -1
- package/package.json +15 -2
package/README.md
CHANGED
|
@@ -1,336 +1,392 @@
|
|
|
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 / mcp" width="444">
|
|
6
|
-
</picture>
|
|
7
|
-
|
|
8
|
-
**Email rendering analysis for AI assistants**
|
|
9
|
-
|
|
10
|
-
[](https://github.com/emailens/mcp/actions/workflows/ci.yml)
|
|
11
|
-
[). Ask Claude to check your email before you send it.
|
|
24
|
-
|
|
25
|
-
Built on [`@emailens/engine`](https://github.com/emailens/engine). Also available as a [GitHub Action](https://github.com/marketplace/actions/emailens-email-preview-check).
|
|
26
|
-
|
|
27
|
-
## Install
|
|
28
|
-
|
|
29
|
-
```bash
|
|
30
|
-
npx -y @emailens/mcp
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
## Setup
|
|
34
|
-
|
|
35
|
-
### Claude Desktop
|
|
36
|
-
|
|
37
|
-
Add to `claude_desktop_config.json`:
|
|
38
|
-
|
|
39
|
-
```json
|
|
40
|
-
{
|
|
41
|
-
"mcpServers": {
|
|
42
|
-
"emailens": {
|
|
43
|
-
"command": "npx",
|
|
44
|
-
"args": ["-y", "@emailens/mcp"]
|
|
45
|
-
}
|
|
46
|
-
}
|
|
47
|
-
}
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
### Claude Code
|
|
51
|
-
|
|
52
|
-
```bash
|
|
53
|
-
claude mcp add emailens -- npx -y @emailens/mcp
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
### With API Key (optional, unlocks screenshots + sharing)
|
|
57
|
-
|
|
58
|
-
```json
|
|
59
|
-
{
|
|
60
|
-
"mcpServers": {
|
|
61
|
-
"emailens": {
|
|
62
|
-
"command": "npx",
|
|
63
|
-
"args": ["-y", "@emailens/mcp"],
|
|
64
|
-
"env": {
|
|
65
|
-
"EMAILENS_API_KEY": "ek_live_..."
|
|
66
|
-
}
|
|
67
|
-
}
|
|
68
|
-
}
|
|
69
|
-
}
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
Get your free API key at [app.emailens.dev/dashboard/api](https://app.emailens.dev/dashboard/api?utm_source=mcp).
|
|
73
|
-
|
|
74
|
-
### Remote (no install)
|
|
75
|
-
|
|
76
|
-
Use the hosted endpoint: no npm or Node.js needed. API key required.
|
|
77
|
-
|
|
78
|
-
```json
|
|
79
|
-
{
|
|
80
|
-
"mcpServers": {
|
|
81
|
-
"emailens": {
|
|
82
|
-
"url": "https://app.emailens.dev/api/mcp",
|
|
83
|
-
"headers": {
|
|
84
|
-
"Authorization": "Bearer ek_live_..."
|
|
85
|
-
}
|
|
86
|
-
}
|
|
87
|
-
}
|
|
88
|
-
}
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
## Tools
|
|
92
|
-
|
|
93
|
-
### Local Tools (no account needed)
|
|
94
|
-
|
|
95
|
-
#### `preview_email`
|
|
96
|
-
|
|
97
|
-
Full email compatibility preview: transforms HTML for 21 clients, analyzes CSS, generates scores, simulates dark mode, checks inbox preview and email size.
|
|
98
|
-
|
|
99
|
-
| Parameter | Type | Required | Description |
|
|
100
|
-
|---|---|---|---|
|
|
101
|
-
| `html` | string | One of | Email HTML source |
|
|
102
|
-
| `path` | string | One of | Absolute path to the source file instead of `html` (`.html`, `.htm`, `.mjml`, `.jsx`, `.tsx`, `.vue`); the extension sets `format` |
|
|
103
|
-
| `clients` | string[] | No | Filter to specific client IDs |
|
|
104
|
-
| `format` | enum | No | `"html"`, `"jsx"`, `"mjml"`, `"maizzle"` |
|
|
105
|
-
|
|
106
|
-
#### `analyze_email`
|
|
107
|
-
|
|
108
|
-
Quick CSS compatibility analysis; returns per-client scores and one finding per problem. Faster than `audit_email` when you only need CSS compatibility.
|
|
109
|
-
|
|
110
|
-
| Parameter | Type | Required | Description |
|
|
111
|
-
|---|---|---|---|
|
|
112
|
-
| `html` | string | One of | Email HTML source |
|
|
113
|
-
| `path` | string | One of | Absolute path to the source file instead of `html` (`.html`, `.htm`, `.mjml`, `.jsx`, `.tsx`, `.vue`); the extension sets `format` |
|
|
114
|
-
| `format` | enum | No | Input format |
|
|
115
|
-
| `detail` | enum | No | `"summary"` (default) or `"full"` |
|
|
116
|
-
| `clients` | string[] | No | Only report these client IDs |
|
|
117
|
-
| `targetingPolicy` | enum | No | `"progressive"` (default), `"strict"`, or `"lenient"` |
|
|
118
|
-
|
|
119
|
-
**One finding per problem, not one per client.** The engine reports per client
|
|
120
|
-
because a score is per client, and per selector because a fix is per selector.
|
|
121
|
-
On an ordinary newsletter `border-radius` arrives twelve times (two clients
|
|
122
|
-
that drop it, six selectors that use it) with the same sentence in every copy.
|
|
123
|
-
That was 286KB of JSON, about 73,000 tokens, for an 11KB email.
|
|
124
|
-
|
|
125
|
-
Findings group by property, severity and message, listing the clients affected,
|
|
126
|
-
with positions merged across all of them. The same email now returns 40KB.
|
|
127
|
-
|
|
128
|
-
```json
|
|
129
|
-
{
|
|
130
|
-
"property": "border-radius",
|
|
131
|
-
"severity": "warning",
|
|
132
|
-
"clients": ["outlook-windows", "outlook-windows-legacy"],
|
|
133
|
-
"message": "Does not support \"border-radius\". Round corners can be used in VML…",
|
|
134
|
-
"fixType": "structural",
|
|
135
|
-
"hasFix": true,
|
|
136
|
-
"loc": { "line": 61, "column": 28, "offset": 2753, "length": 171 },
|
|
137
|
-
"alsoAtLines": [62, 64, 75, 78, 87]
|
|
138
|
-
}
|
|
139
|
-
```
|
|
140
|
-
|
|
141
|
-
Fix snippets are not included; they were 93KB of that 286KB, and `fix_email`
|
|
142
|
-
produces them for the issues you decide to act on. `hasFix` tells you one is
|
|
143
|
-
available; `fixType` tells you whether the repair is markup or CSS.
|
|
144
|
-
|
|
145
|
-
Pass `detail: "full"` for the engine's per-client shape with snippets, and
|
|
146
|
-
`clients: ["gmail-web", "outlook-windows"]` to report only what you care about:
|
|
147
|
-
the fastest further saving, roughly halving the response for two clients.
|
|
148
|
-
Scores stay whole-email either way: narrowing the report does not change what
|
|
149
|
-
the email is worth elsewhere. An unknown client ID is rejected by name; an
|
|
150
|
-
empty result would read as "this email is fine for that client".
|
|
151
|
-
|
|
152
|
-
**Source positions.** For HTML input, every warning carries `loc` (`line`,
|
|
153
|
-
`column`, `offset`, `length`) for the first occurrence, plus `alsoAtLines` for
|
|
154
|
-
any others, so an assistant can edit the exact source and knows where the rest
|
|
155
|
-
are. `audit_email` positions its other findings the same way.
|
|
156
|
-
|
|
157
|
-
```json
|
|
158
|
-
{
|
|
159
|
-
"property": "border-radius",
|
|
160
|
-
"loc": { "line": 7, "column": 8, "offset": 142, "length": 25 },
|
|
161
|
-
"alsoAtLines": [12, 19]
|
|
162
|
-
}
|
|
163
|
-
```
|
|
164
|
-
|
|
165
|
-
Later occurrences are line numbers rather than full positions on purpose: this
|
|
166
|
-
response is read by a model paying for every token, and a real newsletter can
|
|
167
|
-
produce over a thousand occurrences; carrying them all in full nearly doubles
|
|
168
|
-
the payload.
|
|
169
|
-
|
|
170
|
-
Positions are reported for `html` input only. JSX, MJML and Maizzle are compiled
|
|
171
|
-
before analysis, so a line number would point into generated output rather than
|
|
172
|
-
the file you have open: the tools omit it instead of returning one that looks
|
|
173
|
-
authoritative.
|
|
174
|
-
|
|
175
|
-
#### `audit_email`
|
|
176
|
-
|
|
177
|
-
Comprehensive quality audit: CSS compatibility, spam scoring, link validation, accessibility, images, inbox preview, size (Gmail clipping), template variables, content overflow, visual bugs, dark-mode and mobile text contrast, design consistency, and client targeting.
|
|
178
|
-
|
|
179
|
-
The last three cover what a light desktop preview cannot show: text that disappears when a client forces dark mode or when the email's own dark block repaints a surface without re-colouring the text on it, contrast below the email's breakpoint, and colours that differ by value but not to a reader.
|
|
180
|
-
|
|
181
|
-
| Parameter | Type | Required | Description |
|
|
182
|
-
|---|---|---|---|
|
|
183
|
-
| `html` | string | One of | Email HTML source |
|
|
184
|
-
| `path` | string | One of | Absolute path to the source file instead of `html` (`.html`, `.htm`, `.mjml`, `.jsx`, `.tsx`, `.vue`); the extension sets `format` |
|
|
185
|
-
| `format` | enum | No | Input format |
|
|
186
|
-
| `detail` | enum | No | `"summary"` (default) or `"full"` |
|
|
187
|
-
| `clients` | string[] | No | Only report these client IDs |
|
|
188
|
-
| `skip` | string[] | No | Checks to skip (e.g. `["spam", "images"]`) |
|
|
189
|
-
| `targetingPolicy` | enum | No | `"progressive"` (default), `"strict"`, or `"lenient"` |
|
|
190
|
-
| `emailType` | enum | No | `"transactional"` (no unsubscribe link required) or `"marketing"`. Omitted: guessed from the content |
|
|
191
|
-
| `previousHtml` | string | No | The design to hold this version to, usually your first draft. Omitted: the first version of this email audited in the session. What the edits removed comes back as `designRemovals` |
|
|
192
|
-
|
|
193
|
-
Fix `error` and `warning` findings. `info` findings are not problems: the email falls back safely there, so never remove responsive (`@media`) or dark-mode CSS to clear them.
|
|
194
|
-
|
|
195
|
-
#### `fix_email`
|
|
196
|
-
|
|
197
|
-
Generate a structured fix prompt for compatibility issues. Returns markdown with fix instructions that the AI can apply directly.
|
|
198
|
-
|
|
199
|
-
| Parameter | Type | Required | Description |
|
|
200
|
-
|---|---|---|---|
|
|
201
|
-
| `html` | string | One of | Email HTML to fix |
|
|
202
|
-
| `path` | string | One of | Absolute path to the source file instead of `html` (`.html`, `.htm`, `.mjml`, `.jsx`, `.tsx`, `.vue`); the extension sets `format` |
|
|
203
|
-
| `format` | enum | No | Controls fix syntax |
|
|
204
|
-
| `scope` | enum | No | `"all"` or `"current"` |
|
|
205
|
-
| `selectedClientId` | string | No | Client ID for scoped fixes |
|
|
206
|
-
|
|
207
|
-
#### `list_clients`
|
|
208
|
-
|
|
209
|
-
List all 21 supported email clients with IDs, names, engines, and dark mode support.
|
|
210
|
-
|
|
211
|
-
#### `diff_emails`
|
|
212
|
-
|
|
213
|
-
Compare two email HTML versions; shows score changes, fixed issues, and introduced issues per client.
|
|
214
|
-
|
|
215
|
-
| Parameter | Type | Required | Description |
|
|
216
|
-
|---|---|---|---|
|
|
217
|
-
| `before` / `beforePath` | string | One of | Original email source, or its file |
|
|
218
|
-
| `after` / `afterPath` | string | One of | Modified email source, or its file |
|
|
219
|
-
| `format` | enum | No | Input format |
|
|
220
|
-
|
|
221
|
-
#### `check_deliverability`
|
|
222
|
-
|
|
223
|
-
Check email deliverability for a domain: SPF, DKIM, DMARC, MX, BIMI records with a score and actionable issues.
|
|
224
|
-
|
|
225
|
-
| Parameter | Type | Required | Description |
|
|
226
|
-
|---|---|---|---|
|
|
227
|
-
| `domain` | string | Yes | Domain to check (e.g. `"company.com"`) |
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
|
241
|
-
|
|
242
|
-
| `
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
|
294
|
-
|
|
|
295
|
-
|
|
|
296
|
-
|
|
|
297
|
-
|
|
|
298
|
-
|
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
|
307
|
-
|
|
308
|
-
|
|
|
309
|
-
|
|
|
310
|
-
|
|
|
311
|
-
|
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
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 / mcp" width="444">
|
|
6
|
+
</picture>
|
|
7
|
+
|
|
8
|
+
**Email rendering analysis for AI assistants**
|
|
9
|
+
|
|
10
|
+
[](https://github.com/emailens/mcp/actions/workflows/ci.yml)
|
|
11
|
+
[](https://www.npmjs.com/package/@emailens/mcp)
|
|
12
|
+
[](./LICENSE)
|
|
13
|
+
[](https://registry.modelcontextprotocol.io)
|
|
14
|
+
[](https://smithery.ai/servers/emailens-mcp/emailens-mcp)
|
|
15
|
+
[](https://github.com/emailens/mcp/stargazers)
|
|
16
|
+
|
|
17
|
+
</div>
|
|
18
|
+
|
|
19
|
+
MCP server for email compatibility analysis. Analyze, preview, diff, and fix emails across 21 email clients, plus capture real screenshots and create shareable links with an optional API key.
|
|
20
|
+
|
|
21
|
+
Send **HTML, MJML, Maizzle or React Email**. Set `format` and the template is compiled before analysis, so what gets checked is the HTML your readers actually receive.
|
|
22
|
+
|
|
23
|
+
Why your assistant needs this: across the 298 CSS and HTML features we track, only 6 are fully supported in every major email client ([see the data](https://emailens.dev/email-css/report)). Ask Claude to check your email before you send it.
|
|
24
|
+
|
|
25
|
+
Built on [`@emailens/engine`](https://github.com/emailens/engine). Also available as a [GitHub Action](https://github.com/marketplace/actions/emailens-email-preview-check).
|
|
26
|
+
|
|
27
|
+
## Install
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
npx -y @emailens/mcp
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Setup
|
|
34
|
+
|
|
35
|
+
### Claude Desktop
|
|
36
|
+
|
|
37
|
+
Add to `claude_desktop_config.json`:
|
|
38
|
+
|
|
39
|
+
```json
|
|
40
|
+
{
|
|
41
|
+
"mcpServers": {
|
|
42
|
+
"emailens": {
|
|
43
|
+
"command": "npx",
|
|
44
|
+
"args": ["-y", "@emailens/mcp"]
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### Claude Code
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
claude mcp add emailens -- npx -y @emailens/mcp
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### With API Key (optional, unlocks screenshots + sharing)
|
|
57
|
+
|
|
58
|
+
```json
|
|
59
|
+
{
|
|
60
|
+
"mcpServers": {
|
|
61
|
+
"emailens": {
|
|
62
|
+
"command": "npx",
|
|
63
|
+
"args": ["-y", "@emailens/mcp"],
|
|
64
|
+
"env": {
|
|
65
|
+
"EMAILENS_API_KEY": "ek_live_..."
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Get your free API key at [app.emailens.dev/dashboard/api](https://app.emailens.dev/dashboard/api?utm_source=mcp).
|
|
73
|
+
|
|
74
|
+
### Remote (no install)
|
|
75
|
+
|
|
76
|
+
Use the hosted endpoint: no npm or Node.js needed. API key required.
|
|
77
|
+
|
|
78
|
+
```json
|
|
79
|
+
{
|
|
80
|
+
"mcpServers": {
|
|
81
|
+
"emailens": {
|
|
82
|
+
"url": "https://app.emailens.dev/api/mcp",
|
|
83
|
+
"headers": {
|
|
84
|
+
"Authorization": "Bearer ek_live_..."
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
## Tools
|
|
92
|
+
|
|
93
|
+
### Local Tools (no account needed)
|
|
94
|
+
|
|
95
|
+
#### `preview_email`
|
|
96
|
+
|
|
97
|
+
Full email compatibility preview: transforms HTML for 21 clients, analyzes CSS, generates scores, simulates dark mode, checks inbox preview and email size.
|
|
98
|
+
|
|
99
|
+
| Parameter | Type | Required | Description |
|
|
100
|
+
|---|---|---|---|
|
|
101
|
+
| `html` | string | One of | Email HTML source |
|
|
102
|
+
| `path` | string | One of | Absolute path to the source file instead of `html` (`.html`, `.htm`, `.mjml`, `.jsx`, `.tsx`, `.vue`); the extension sets `format` |
|
|
103
|
+
| `clients` | string[] | No | Filter to specific client IDs |
|
|
104
|
+
| `format` | enum | No | `"html"`, `"jsx"`, `"mjml"`, `"maizzle"` |
|
|
105
|
+
|
|
106
|
+
#### `analyze_email`
|
|
107
|
+
|
|
108
|
+
Quick CSS compatibility analysis; returns per-client scores and one finding per problem. Faster than `audit_email` when you only need CSS compatibility.
|
|
109
|
+
|
|
110
|
+
| Parameter | Type | Required | Description |
|
|
111
|
+
|---|---|---|---|
|
|
112
|
+
| `html` | string | One of | Email HTML source |
|
|
113
|
+
| `path` | string | One of | Absolute path to the source file instead of `html` (`.html`, `.htm`, `.mjml`, `.jsx`, `.tsx`, `.vue`); the extension sets `format` |
|
|
114
|
+
| `format` | enum | No | Input format |
|
|
115
|
+
| `detail` | enum | No | `"summary"` (default) or `"full"` |
|
|
116
|
+
| `clients` | string[] | No | Only report these client IDs |
|
|
117
|
+
| `targetingPolicy` | enum | No | `"progressive"` (default), `"strict"`, or `"lenient"` |
|
|
118
|
+
|
|
119
|
+
**One finding per problem, not one per client.** The engine reports per client
|
|
120
|
+
because a score is per client, and per selector because a fix is per selector.
|
|
121
|
+
On an ordinary newsletter `border-radius` arrives twelve times (two clients
|
|
122
|
+
that drop it, six selectors that use it) with the same sentence in every copy.
|
|
123
|
+
That was 286KB of JSON, about 73,000 tokens, for an 11KB email.
|
|
124
|
+
|
|
125
|
+
Findings group by property, severity and message, listing the clients affected,
|
|
126
|
+
with positions merged across all of them. The same email now returns 40KB.
|
|
127
|
+
|
|
128
|
+
```json
|
|
129
|
+
{
|
|
130
|
+
"property": "border-radius",
|
|
131
|
+
"severity": "warning",
|
|
132
|
+
"clients": ["outlook-windows", "outlook-windows-legacy"],
|
|
133
|
+
"message": "Does not support \"border-radius\". Round corners can be used in VML…",
|
|
134
|
+
"fixType": "structural",
|
|
135
|
+
"hasFix": true,
|
|
136
|
+
"loc": { "line": 61, "column": 28, "offset": 2753, "length": 171 },
|
|
137
|
+
"alsoAtLines": [62, 64, 75, 78, 87]
|
|
138
|
+
}
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Fix snippets are not included; they were 93KB of that 286KB, and `fix_email`
|
|
142
|
+
produces them for the issues you decide to act on. `hasFix` tells you one is
|
|
143
|
+
available; `fixType` tells you whether the repair is markup or CSS.
|
|
144
|
+
|
|
145
|
+
Pass `detail: "full"` for the engine's per-client shape with snippets, and
|
|
146
|
+
`clients: ["gmail-web", "outlook-windows"]` to report only what you care about:
|
|
147
|
+
the fastest further saving, roughly halving the response for two clients.
|
|
148
|
+
Scores stay whole-email either way: narrowing the report does not change what
|
|
149
|
+
the email is worth elsewhere. An unknown client ID is rejected by name; an
|
|
150
|
+
empty result would read as "this email is fine for that client".
|
|
151
|
+
|
|
152
|
+
**Source positions.** For HTML input, every warning carries `loc` (`line`,
|
|
153
|
+
`column`, `offset`, `length`) for the first occurrence, plus `alsoAtLines` for
|
|
154
|
+
any others, so an assistant can edit the exact source and knows where the rest
|
|
155
|
+
are. `audit_email` positions its other findings the same way.
|
|
156
|
+
|
|
157
|
+
```json
|
|
158
|
+
{
|
|
159
|
+
"property": "border-radius",
|
|
160
|
+
"loc": { "line": 7, "column": 8, "offset": 142, "length": 25 },
|
|
161
|
+
"alsoAtLines": [12, 19]
|
|
162
|
+
}
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
Later occurrences are line numbers rather than full positions on purpose: this
|
|
166
|
+
response is read by a model paying for every token, and a real newsletter can
|
|
167
|
+
produce over a thousand occurrences; carrying them all in full nearly doubles
|
|
168
|
+
the payload.
|
|
169
|
+
|
|
170
|
+
Positions are reported for `html` input only. JSX, MJML and Maizzle are compiled
|
|
171
|
+
before analysis, so a line number would point into generated output rather than
|
|
172
|
+
the file you have open: the tools omit it instead of returning one that looks
|
|
173
|
+
authoritative.
|
|
174
|
+
|
|
175
|
+
#### `audit_email`
|
|
176
|
+
|
|
177
|
+
Comprehensive quality audit: CSS compatibility, spam scoring, link validation, accessibility, images, inbox preview, size (Gmail clipping), template variables, content overflow, visual bugs, dark-mode and mobile text contrast, design consistency, and client targeting.
|
|
178
|
+
|
|
179
|
+
The last three cover what a light desktop preview cannot show: text that disappears when a client forces dark mode or when the email's own dark block repaints a surface without re-colouring the text on it, contrast below the email's breakpoint, and colours that differ by value but not to a reader.
|
|
180
|
+
|
|
181
|
+
| Parameter | Type | Required | Description |
|
|
182
|
+
|---|---|---|---|
|
|
183
|
+
| `html` | string | One of | Email HTML source |
|
|
184
|
+
| `path` | string | One of | Absolute path to the source file instead of `html` (`.html`, `.htm`, `.mjml`, `.jsx`, `.tsx`, `.vue`); the extension sets `format` |
|
|
185
|
+
| `format` | enum | No | Input format |
|
|
186
|
+
| `detail` | enum | No | `"summary"` (default) or `"full"` |
|
|
187
|
+
| `clients` | string[] | No | Only report these client IDs |
|
|
188
|
+
| `skip` | string[] | No | Checks to skip (e.g. `["spam", "images"]`) |
|
|
189
|
+
| `targetingPolicy` | enum | No | `"progressive"` (default), `"strict"`, or `"lenient"` |
|
|
190
|
+
| `emailType` | enum | No | `"transactional"` (no unsubscribe link required) or `"marketing"`. Omitted: guessed from the content |
|
|
191
|
+
| `previousHtml` | string | No | The design to hold this version to, usually your first draft. Omitted: the first version of this email audited in the session. What the edits removed comes back as `designRemovals` |
|
|
192
|
+
|
|
193
|
+
Fix `error` and `warning` findings. `info` findings are not problems: the email falls back safely there, so never remove responsive (`@media`) or dark-mode CSS to clear them.
|
|
194
|
+
|
|
195
|
+
#### `fix_email`
|
|
196
|
+
|
|
197
|
+
Generate a structured fix prompt for compatibility issues. Returns markdown with fix instructions that the AI can apply directly.
|
|
198
|
+
|
|
199
|
+
| Parameter | Type | Required | Description |
|
|
200
|
+
|---|---|---|---|
|
|
201
|
+
| `html` | string | One of | Email HTML to fix |
|
|
202
|
+
| `path` | string | One of | Absolute path to the source file instead of `html` (`.html`, `.htm`, `.mjml`, `.jsx`, `.tsx`, `.vue`); the extension sets `format` |
|
|
203
|
+
| `format` | enum | No | Controls fix syntax |
|
|
204
|
+
| `scope` | enum | No | `"all"` or `"current"` |
|
|
205
|
+
| `selectedClientId` | string | No | Client ID for scoped fixes |
|
|
206
|
+
|
|
207
|
+
#### `list_clients`
|
|
208
|
+
|
|
209
|
+
List all 21 supported email clients with IDs, names, engines, and dark mode support.
|
|
210
|
+
|
|
211
|
+
#### `diff_emails`
|
|
212
|
+
|
|
213
|
+
Compare two email HTML versions; shows score changes, fixed issues, and introduced issues per client.
|
|
214
|
+
|
|
215
|
+
| Parameter | Type | Required | Description |
|
|
216
|
+
|---|---|---|---|
|
|
217
|
+
| `before` / `beforePath` | string | One of | Original email source, or its file |
|
|
218
|
+
| `after` / `afterPath` | string | One of | Modified email source, or its file |
|
|
219
|
+
| `format` | enum | No | Input format |
|
|
220
|
+
|
|
221
|
+
#### `check_deliverability`
|
|
222
|
+
|
|
223
|
+
Check email deliverability for a domain: SPF, DKIM, DMARC, MX, BIMI records with a score and actionable issues.
|
|
224
|
+
|
|
225
|
+
| Parameter | Type | Required | Description |
|
|
226
|
+
|---|---|---|---|
|
|
227
|
+
| `domain` | string | Yes | Domain to check (e.g. `"company.com"`) |
|
|
228
|
+
|
|
229
|
+
#### `check_design`
|
|
230
|
+
|
|
231
|
+
Whether the email still looks like its design in each client's live preview.
|
|
232
|
+
It draws the email in a real browser twice: as the client shows it, and as
|
|
233
|
+
you wrote it. Then it compares the two layouts element by element. Each
|
|
234
|
+
client gets a verdict, `kept` (Ready), `changed` (Needs work) or `broken`
|
|
235
|
+
(Broken), with the reasons: columns that stack, a button that moved or
|
|
236
|
+
resized, a fill or corners lost, fonts and spacing changed. This is the
|
|
237
|
+
verdict the Emailens email page shows. An agent can call it after an edit to
|
|
238
|
+
confirm the fix didn't break the layout somewhere else.
|
|
239
|
+
|
|
240
|
+
| Parameter | Type | Required | Description |
|
|
241
|
+
|---|---|---|---|
|
|
242
|
+
| `html` | string | One of | Email HTML source |
|
|
243
|
+
| `path` | string | One of | Absolute path to the source file instead of `html` |
|
|
244
|
+
| `clients` | string[] | No | Client IDs to check. Default: all 21 (a few seconds each, four at a time) |
|
|
245
|
+
| `format` | enum | No | Input format |
|
|
246
|
+
|
|
247
|
+
```json
|
|
248
|
+
{ "broken": ["outlook-windows-legacy"],
|
|
249
|
+
"results": [{ "clientId": "outlook-windows-legacy", "name": "Outlook Classic",
|
|
250
|
+
"verdict": "broken", "label": "Broken",
|
|
251
|
+
"sentence": "Outlook Classic breaks your design.",
|
|
252
|
+
"reasons": ["Columns that sit side by side in your design stack on top of each other."],
|
|
253
|
+
"more": 0 }] }
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
It needs a browser. Add `playwright-core` to the server, and `sharp` for the
|
|
257
|
+
pixel comparison. Then either install a local Chromium or point it at your
|
|
258
|
+
Browserless instance:
|
|
259
|
+
|
|
260
|
+
```json
|
|
261
|
+
{
|
|
262
|
+
"mcpServers": {
|
|
263
|
+
"emailens": {
|
|
264
|
+
"command": "npx",
|
|
265
|
+
"args": ["-y", "-p", "@emailens/mcp", "-p", "playwright-core", "-p", "sharp", "emailens-mcp"],
|
|
266
|
+
"env": { "BROWSERLESS_URL": "wss://..." }
|
|
267
|
+
}
|
|
268
|
+
}
|
|
269
|
+
}
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
Without `BROWSERLESS_URL`, it uses a local Chromium. Install one with
|
|
273
|
+
`npx playwright-core install chromium`. A few more things to know:
|
|
274
|
+
- It runs in light mode, against our live preview, not real inboxes.
|
|
275
|
+
- With `sharp`, it also compares screenshots of the two pages pixel by
|
|
276
|
+
pixel, as the hosted check does. That agrees more often with a human
|
|
277
|
+
reviewer, and each result carries `diff` (the share of pixels off) and
|
|
278
|
+
`aligned`. Without `sharp`, it compares page structure only.
|
|
279
|
+
- On Browserless, the session has to stay open for the whole call. Raise a
|
|
280
|
+
short `TIMEOUT`, or pass fewer `clients`.
|
|
281
|
+
- Scripts are off in both pages.
|
|
282
|
+
- The font stand-ins the previews use are downloaded once from
|
|
283
|
+
app.emailens.dev into `~/.cache/emailens/fonts`.
|
|
284
|
+
|
|
285
|
+
### Hosted Tools (require `EMAILENS_API_KEY`)
|
|
286
|
+
|
|
287
|
+
#### `capture_screenshots`
|
|
288
|
+
|
|
289
|
+
Capture real email screenshots across 21 clients in real browsers. Screenshots are hosted on CDN.
|
|
290
|
+
|
|
291
|
+
| Parameter | Type | Required | Description |
|
|
292
|
+
|---|---|---|---|
|
|
293
|
+
| `html` | string | One of | Email HTML source |
|
|
294
|
+
| `path` | string | One of | Absolute path to the source file instead of `html` (`.html`, `.htm`, `.mjml`, `.jsx`, `.tsx`, `.vue`); the extension sets `format` |
|
|
295
|
+
| `format` | enum | No | Input format |
|
|
296
|
+
| `clients` | string[] | No | Filter clients |
|
|
297
|
+
| `modes` | string[] | No | `["light"]`, `["dark"]`, or `["light", "dark"]` |
|
|
298
|
+
| `title` | string | No | Name for the preview |
|
|
299
|
+
|
|
300
|
+
Free plan: 30 previews/day. [Sign up](https://emailens.dev/?utm_source=mcp)
|
|
301
|
+
|
|
302
|
+
#### `share_preview`
|
|
303
|
+
|
|
304
|
+
Create a shareable link. Recipients see the full analysis without an account.
|
|
305
|
+
|
|
306
|
+
| Parameter | Type | Required | Description |
|
|
307
|
+
|---|---|---|---|
|
|
308
|
+
| `html` | string | One of | Email HTML source |
|
|
309
|
+
| `path` | string | One of | Absolute path to the source file instead of `html` (`.html`, `.htm`, `.mjml`, `.jsx`, `.tsx`, `.vue`); the extension sets `format` |
|
|
310
|
+
| `title` | string | No | Display title |
|
|
311
|
+
| `format` | enum | No | Input format |
|
|
312
|
+
|
|
313
|
+
Requires Dev plan ($9/mo). Share links expire after 7 days (Dev) or never (Pro).
|
|
314
|
+
|
|
315
|
+
## Template formats
|
|
316
|
+
|
|
317
|
+
`format` accepts `html` (the default), `mjml`, `maizzle` and `jsx` (React
|
|
318
|
+
Email). `maizzle` is an HTML template or a Vue single-file component. A pasted
|
|
319
|
+
Vue file with no `format` is compiled as `maizzle`. Anything but `html` is
|
|
320
|
+
compiled before analysis and also decides the syntax the fix snippets come back in.
|
|
321
|
+
|
|
322
|
+
Compiling matters more than it sounds. An email client renders the *output*, so
|
|
323
|
+
that is what has to be checked: handed a raw `<mjml>` document, an HTML parser
|
|
324
|
+
finds no CSS in it and reports a perfectly clean email. An answer like that is
|
|
325
|
+
worse than an error, because an assistant will repeat it.
|
|
326
|
+
|
|
327
|
+
**The compilers are not bundled.** MJML alone pulls 56MB, and this server is
|
|
328
|
+
usually started with `npx`, so the engine keeps them as optional peer
|
|
329
|
+
dependencies:
|
|
330
|
+
|
|
331
|
+
```bash
|
|
332
|
+
npm install mjml # MJML
|
|
333
|
+
npm install @maizzle/framework@5 # Maizzle HTML
|
|
334
|
+
npm install @maizzle/framework@6 # Maizzle Vue single-file components
|
|
335
|
+
npm install sucrase react @react-email/components @react-email/render # React Email
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
They have to be installed where the server runs, which is not always somewhere
|
|
339
|
+
you control. If it is not, compile the template yourself and send the resulting
|
|
340
|
+
HTML with `format: "html"`: the tools say so when they hit this.
|
|
341
|
+
|
|
342
|
+
## Supported Email Clients (21)
|
|
343
|
+
|
|
344
|
+
Each client links to its CSS support page. Setup guides for every assistant: [emailens.dev/mcp](https://emailens.dev/mcp).
|
|
345
|
+
|
|
346
|
+
| Client | ID | Dark Mode | Notes |
|
|
347
|
+
|---|---|---|---|
|
|
348
|
+
| [Gmail](https://emailens.dev/email-css/clients/gmail-web) | `gmail-web` | Yes | |
|
|
349
|
+
| [Gmail Android](https://emailens.dev/email-css/clients/gmail-android) | `gmail-android` | Yes | |
|
|
350
|
+
| [Gmail iOS](https://emailens.dev/email-css/clients/gmail-ios) | `gmail-ios` | Yes | |
|
|
351
|
+
| [Outlook 365](https://emailens.dev/email-css/clients/outlook-web) | `outlook-web` | Yes | |
|
|
352
|
+
| [Outlook Windows](https://emailens.dev/email-css/clients/outlook-windows) | `outlook-windows` | No | |
|
|
353
|
+
| [Outlook Windows Legacy](https://emailens.dev/email-css/clients/outlook-windows-legacy) | `outlook-windows-legacy` | No | Deprecated Oct 2026 |
|
|
354
|
+
| [Outlook iOS](https://emailens.dev/email-css/clients/outlook-ios) | `outlook-ios` | Yes | New in v0.4.0 |
|
|
355
|
+
| [Outlook Android](https://emailens.dev/email-css/clients/outlook-android) | `outlook-android` | Yes | New in v0.4.0 |
|
|
356
|
+
| [Outlook for Mac](https://emailens.dev/email-css/clients/outlook-macos) | `outlook-macos` | Yes | New in v0.10.0 |
|
|
357
|
+
| [Apple Mail](https://emailens.dev/email-css/clients/apple-mail-macos) | `apple-mail-macos` | Yes | |
|
|
358
|
+
| [Apple Mail iOS](https://emailens.dev/email-css/clients/apple-mail-ios) | `apple-mail-ios` | Yes | |
|
|
359
|
+
| [Yahoo Mail](https://emailens.dev/email-css/clients/yahoo-mail) | `yahoo-mail` | Yes | |
|
|
360
|
+
| [Yahoo Mail Android](https://emailens.dev/email-css/clients/yahoo-mail-android) | `yahoo-mail-android` | Yes | New in v0.10.0 |
|
|
361
|
+
| [Yahoo Mail iOS](https://emailens.dev/email-css/clients/yahoo-mail-ios) | `yahoo-mail-ios` | Yes | New in v0.10.0 |
|
|
362
|
+
| [Samsung Mail](https://emailens.dev/email-css/clients/samsung-mail) | `samsung-mail` | Yes | |
|
|
363
|
+
| [Thunderbird](https://emailens.dev/email-css/clients/thunderbird) | `thunderbird` | No | |
|
|
364
|
+
| [HEY Mail](https://emailens.dev/email-css/clients/hey-mail) | `hey-mail` | Yes | |
|
|
365
|
+
| [Proton Mail](https://emailens.dev/email-css/clients/protonmail) | `protonmail` | Yes | New in v0.10.0 |
|
|
366
|
+
| [AOL Mail](https://emailens.dev/email-css/clients/aol) | `aol` | Yes | New in v0.10.0 |
|
|
367
|
+
| [Fastmail](https://emailens.dev/email-css/clients/fastmail) | `fastmail` | Yes | New in v0.10.0 |
|
|
368
|
+
| [Superhuman](https://emailens.dev/email-css/clients/superhuman) | `superhuman` | Yes | |
|
|
369
|
+
|
|
370
|
+
## Releasing
|
|
371
|
+
|
|
372
|
+
Two publishes: npm, and the MCP registry. The registry listing sat five
|
|
373
|
+
releases behind because nothing pushed `server.json`, so that half is a
|
|
374
|
+
workflow now. [RELEASING.md](./RELEASING.md) has the details and the four
|
|
375
|
+
places the version has to agree.
|
|
376
|
+
|
|
377
|
+
## Development
|
|
378
|
+
|
|
379
|
+
```bash
|
|
380
|
+
bun install
|
|
381
|
+
bun run build
|
|
382
|
+
bun test
|
|
383
|
+
bun run typecheck
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
## License
|
|
387
|
+
|
|
388
|
+
MIT
|
|
389
|
+
|
|
390
|
+
---
|
|
391
|
+
|
|
392
|
+
If this saved you from an Outlook surprise, [a star](https://github.com/emailens/mcp) helps other email developers find it.
|