KechuAI

Email.md：用 Markdown 写响应式邮件，底层是 MJML，还自带 MCP server

邮件
Markdown
开源
前端
AI
MCP
2026/10/4
·

阅读时间: 大约 11 分钟

Email.md：用 Markdown 写响应式邮件，底层是 MJML，还自带 MCP server

emailmd 的核心体验：左边是 confirm-email.md 源码（frontmatter + ::: header/callout/footer 指令），右边是渲染出的深色邮件预览

写一封能在 Outlook 里看的 HTML 邮件，是前端领域著名的”时间黑洞”。官方文档把原因说得很直白：邮件客户端从来没有统一的渲染引擎——Outlook 至今仍在用 Microsoft Word 的排版引擎渲染 HTML，Gmail 会剥离 <style> 标签与大部分 CSS，Yahoo 又有自己的怪癖。在 Apple Mail 里完美的布局，到 Outlook 里可能直接散架。于是手写邮件最终都退化成”层层嵌套的表格 + 内联样式 + 客户端专属 hack”。emailmd（npm install emailmd）给出的解法是：你只写 Markdown，剩下的交给它。本文基于其官网 emailmd.dev 与 GitHub README 做一手梳理，项目由 unMTA 团队维护、Anypost 赞助，MIT 协议。

一、它解决什么：把”HTMHELL”藏进一行 render()

emailmd 的口号是 “Write markdown. Ship emails. No HTMHELL.”。核心 API 极小：

import { render } from "emailmd";
const { html, text } = await render(`# Welcome! ...`);
// html → 完整的 email-safe HTML
// text → text/plain 纯文本版本

两个返回值都很关键：html 是可直接投递的、跨客户端兼容的邮件 HTML；text 是自动生成的纯文本 MIME 备用部分——而不是让你手写两份。底层它调用 MJML 来产出”bulletproof email HTML”，自己则在 Markdown 与 MJML 之间做了一层语义映射。

语法上它不是”纯 Markdown”，而是 Markdown + 一组 ::: 围栏指令：::: header、::: callout、::: footer、::: chart，按钮写成 [Get Started](url){button}，主题与预头等元信息写在 frontmatter（见上图左侧源码）。官方模板库提供 13 个开箱即用的生产级模板。

二、技术机制：图表不用图片，用表格单元格和文字字形

这是 emailmd 最值得说的工程选择。看下图——一封深色周报邮件里有四个 KPI 块、一组横向条形对比、一组每集播放量的迷你柱：

emailmd 渲染的深色数据邮件：KPI 块、横向条形图、迷你柱状图全部由表格单元格与文字字形绘制，不依赖图片或 SVG

按 README 的说法，这些”图表”不是图片、不是 SVG，而是从表格单元格和文字字形画出来的。这个选择带来两个邮件场景下非常实际的好处：

  1. 客户端屏蔽远程图片时仍然可读：很多邮件客户端默认不加载远程图片（Outlook、企业网关常如此），如果数据图是 <img>，收件人看到的就是一片空白；用表格 + 单元格底色拼出来的条，无论图片是否加载都在；
  2. 纯文本部分能降级为 ASCII：官方称这些图在 text/plain 里会”redraw themselves”而不是坍缩成一串数字——也就是说纯文本收件人也能读到图表的大致形状。

支持的图表族包括：柱状图、进度条、sparkline 迷你趋势线、KPI 数字块、步骤追踪器、星级评分。Markdown 里写出来就是一个普通列表：

::: chart
- Spotify: 16,900
- Apple Podcasts: 12,400
- Web player: 6,200
- RSS: 2,900
:::

三、给 AI 用：一个带 live preview 的 MCP server

emailmd 把”AI 友好”当成一等设计，而且不只靠”Markdown 好写”：

  • MCP server：暴露三个工具——render（markdown → email-safe HTML）、lint（不渲染就标出送达率/可访问性问题）、read_docs（查语法）。托管端点 https://www.emailmd.dev/api/mcp（Streamable HTTP），或本地 npx emailmd mcp（stdio）；已发布到官方 MCP registry，名称 dev.emailmd/emailmd，一键接入 Claude Code、Claude Desktop、ChatGPT、Cursor、VS Code；
  • llms-full.txt：给不支持 MCP 的 AI 工具喂完整文档；
  • @emailmd/react：useEmailmd 实时预览 hook、<EmailPreview /> iframe、以及可直接嵌入你自己应用的 <EmailmdBuilder /> 可视化编辑器；
  • CLI：emailmd input.md -o output.html --text，也支持管道输入。

四、关键口径：官方自己承认的边界

这篇文章必须把几处宣传背后的口径写清楚：

  1. 官方自称只覆盖”80%+ 的邮件设计需求”：文档原文是 “It won’t cover every edge case a hand-crafted HTML email can, but it handles 80%+ of email design needs in a fraction of the time”。也就是说，极度定制、像素级对齐的品牌邮件，仍然需要专业 HTML 邮件工程师。
  2. 还没到 1.0，API 会变：README 明确 “emailmd is under active development. The API may change between minor versions until we hit 1.0”；v0.3.0 是个破坏性升级——render() 从同步改成异步、要求 Node 20+（MJML 5）。现在引入意味着要跟得上它的 changelog。
  3. 它是 MJML 的上层封装，不是新引擎：兼容性边界继承自 MJML。MJML 本身解决不了的极端客户端怪癖，emailmd 也解决不了；出问题时排查路径要往下钻一层。
  4. 字形图表的代价是视觉上限：用表格单元格拼出来的”柱状图”没有真正的坐标轴、刻度和数据精度控制，它是一种”邮件里的数据可视化示意”，不是 BI 图表。想做精确数据探索的邮件不适合。
  5. 深色模式”跟随读者偏好”在邮件里并不可靠：@media (prefers-color-scheme) 在 Gmail 网页版、Outlook 各版本里支持参差，官方的自动暗色主题在多少客户端真能生效，需要自己过一遍测试矩阵。

五、优势与局限

优势：

  1. 把邮件兼容性问题从”前端手艺活”降级为”写 Markdown”，并自动产出 text/plain；
  2. 无图片图表在邮件这个”远程图片默认被拦”的环境里是真痛点解决，而不是炫技；
  3. MCP server + lint 让 AI 写邮件形成闭环：写、查、渲染、给预览链接，而不是只生成一段要你自己调试的 HTML；
  4. MIT、npm 包 + CLI + React 组件 + 托管 MCP 四种用法，从脚本到可视化编辑器都覆盖。

局限：

  1. 未到 1.0，API 不稳定，生产链路接入要锁版本；
  2. 能力上限就是 MJML 的上限，超复杂版式要自己写扩展；
  3. 图表表达力有限，适合周报/账单里的”数据感”点缀，不适合承载严肃数据分析；
  4. 生态年轻：模板、社区案例比 MJML/Handlebars 老牌方案少得多。

六、谁该关注它

  • 发事务性邮件的 SaaS 团队：验证邮件、周报、账单摘要——正是它 80% 覆盖区；
  • 用 AI 编码助手做营销/运营邮件的小团队：MCP server 让”让 AI 写一封注册引导邮件”变成可 lint、可预览的闭环；
  • 受够了嵌套表格的前端：用 Markdown + 指令写邮件，维护成本骤降。

但如果你要做的是季度股东大会那种像素级品牌邮件，或者需要交互式数据图表，emailmd 目前还不是那个工具。

参考来源