marclou/mailcheap · 上手攻略

  • 仓库：marclou/mailcheap
  • 链接：https://github.com/marclou/mailcheap
  • 分类：agent / 自托管 Newsletter 平台 / 邮件 SaaS
  • 作者：spark
  • 更新：2026-10-15

§0 自检(三证 checklist)

  • ✅ GitHub URL 已 fetch:仓库 README(2026-10-14 抓取)含完整功能描述、组件清单、Vercel 部署按钮、依赖服务表。
  • ⚠️ 顶会/学术 venue:本仓库是 AGPL-3.0 应用层产品,无 anchor 学术 venue。
  • ✅ README 子模块 anchor 已列:/api/v1 REST API、/mcp MCP server、/docs Swagger UI、/llms.txt、截图目录 docs/screenshots/、MailCheap Cloud (MAILCHEAP_CLOUD=true)开关位。

关键事实 verbatim 来自 README:AGPL-3.0、Self-hosted 价格 = "Free, plus what your provider charges per email"、Cloud 起步 $19/month、bounce 暂停阈值 2% / 5 个硬退、0.08% / 2 个投诉、Cloud 首 30 天渐进 24→16→12→8 小时窗口、QStash "One message sends 50 emails" 等。setup 时长 "about an hour" 也是 README 原话。版本号、QStash 当前定价、Resend 价格未独立核实,凡涉成本数字均以官方账单为准。

1. 它是什么?解决什么问题?

MailCheap 是开源的 newsletter 应用,定位:"the affordable newsletter for the agentic era"——一次性给你写邮件、列表、signup、统计、公开 archive、AI 友好的 REST + MCP 接口。整套就是一个 Next.js 应用。

它要解决两难:

  1. Substack / Beehiiv / ConvertKit 这种平台,按订阅数每月收钱——10,000 读者 4 期/月 = 40,000 封,MailCheap + SES 约 $4~$6。
  2. 自己拼开源,要从 IMAP、IP 信誉、unsubscribe link、bounce/complaint 反馈一个个填坑——MailCheap 把这些都内置好了,直接对接 Amazon SES 或 PostShiba 就完事。

核心差异化:"AI agent 友好"——所有 dashboard 行为都同时暴露为 REST API 和 MCP server,自动化一条龙。

2. 快速部署

2.1 一键 Vercel(README 主推)

仓库 README 给了官方 Vercel 部署按钮:

https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fmarclou%2Fmailcheap
&project-name=mailcheap
&repository-name=mailcheap
&env=MONGODB_URI,BETTER_AUTH_SECRET,ADMIN_EMAILS,EMAIL_FROM

需要 4 个环境变量:

变量 含义 示例 / 生成方式
MONGODB_URI MongoDB 连接串 mongodb+srv://user:pwd@cluster0.xxxx.mongodb.net/mailcheap?retryWrites=true(库名加在 ? 之前)
BETTER_AUTH_SECRET 签名密钥,≥32 字符 openssl rand -base64 48
ADMIN_EMAILS 允许登录并进 /admin 的邮箱 你的邮箱
EMAIL_FROM 验证码 / 通知邮件的发件人 MailCheap <hi@yourdomain.com>,域名必须先在 Resend / SES / PostShiba 验证

可选变量(影响具体功能):

  • RESEND_API_KEY — 让验证码走 Resend,最快搞定登录邮件
  • EMAIL_PROVIDER + SES 或 PostShiba 凭据 — 真正给读者发 newsletter
  • QSTASH_TOKEN — Upstash QStash 后台分批发送
  • S3 / CloudFront 或 BLOB_READ_WRITE_TOKEN(Vercel Blob)— 编辑器图床
  • UPSTASH_REDIS_REST_* — 多实例共享 rate limit

⚠️ README 原话:短于 32 字符的 BETTER_AUTH_SECRET 直接拒启动,日志会说明原因。

2.2 任意 Node.js 主机

npm ci && npm run build && npm start

环境变量同上,跑在 HTTPS 后。健康检查:GET /api/health 返回 200,否则 503 + 修复提示。

2.3 自建预计耗时

README 原话:"Plan for about an hour, most of it waiting for DNS and for your provider to approve production sending." 大头是等 SES 批生产权限(通常 1 天内),DNS 解析传播 5~30 分钟。

3. 核心用法

3.1 编辑器(Editor)

  • 实时邮件预览,slash 命令 + 块(boxes)
  • 图片:拖入 / 粘贴 / 从历史图床选;支持 Markdown + 原始 HTML
  • 每发送前自动检查:subject、preview text、unsubscribe 链接、Gmail 100 KB clip 阈值、邮政地址(法律要求)、域名已验证
  • 测试邮件、调度、QStash 分批发送

阶梯发送(README 重点功能):首发给从没发过的联系人群时自动分阶——先发 5% 切片,3 小时后根据退信/投诉情况发剩下:

"A first send to contacts never mailed goes out in steps by itself: a 5% slice, then the rest 3 hours later if its bounces and complaints stay low."

Cloud 模式额外对新账号前 30 天有 24 → 16 → 12 → 8 小时 的渐进节奏。

3.2 增长(列表管理)

  • 公开 archive 内嵌 signup 表单 + signup API(用 API key)
  • 默认 confirmed opt-in + welcome 邮件
  • CSV 导入清洗:跳过无效、拼错(gmial.com)、垃圾陷阱、role 邮箱、临时邮箱、重复、被压制的地址,并记录用户同意
  • signup 表单拒绝拼错的邮箱,并给建议
  • 手动加联系人(已确认同意前提下)立即入列表,无需 confirm
  • 全套默认 rate limit:signup / signin / unsubscribe / slug 修改 / API / dashboard 测试邮件 / 发送 / 导入 / 上传。账号的 API key / 接的 App / dashboard 共用配额,多 key 不提升额度——避免被多个 key 绕过。

3.3 健康度(发送防护)

暂停阈值(README verbatim):

触发条件 阈值
硬退信率 > 2%(至少 5 封)
投诉率 > 0.08%(至少 2 个)
滥用 block send / 首发送切片 / 过去 7 天 > 5%(≥10)硬退或 0.3%(≥3)投诉 / 垃圾陷阱命中 / 邮件服务商封号

单次投诉不会停任何东西——避免偶发投诉误杀账号。被 block 时所有发送停止,包括 welcome 邮件,等 admin 解封。

  • One-click unsubscribe(RFC 8058 List-Unsubscribe header)+ 签名 unsubscribe 页面
  • 自动列表清理(默认开):连续多次不读的读者会收到一封"还想继续吗?",不回就停发
  • 自有域上的打开 / 点击追踪,过滤 link scanner

3.4 公开 archive + 统计

  • 公开 issue 页、作者页、分享图、sitemap,archive 可挂在自己的子域
  • 总览:订阅者趋势、每小时发送量、投递 / 打开 / 点击 / 退信 / 投诉率
  • 按 邮箱服务商(Gmail / Outlook / Yahoo / iCloud / ...)拆分的 campaign 报告
  • 域名页:每个域的 DKIM / return-path 状态 + 要加的 DNS 记录

3.5 账号

  • 邮箱验证码登录 / Google 登录;自托管只允许白名单邮箱
  • 每人 1 个账号,最多 3 个 newsletter,共享账号的 domain 和 API key
  • Admin 看所有账号,可 block / unblock,Cloud 模式可送免费 plan
  • 账号删除:立即停服,30 天后真删数据,期间登录可恢复

3.6 给 Agent 用的接口

入口 说明
GET /api/v1/... REST API,跟 dashboard 用同一套 API key、同样的发送前校验
/mcp MCP server(同套凭据)
/docs Swagger UI
/llms.txt 给你 LLM / agent 读的精简文档

这是 MailCheap 跟同类最大的差异——一个 newsletter 平台,居然原生暴露 MCP。

4. 典型适用场景

  • 个人 / 小团队 newsletter:不想被 Substack 抽成 10%,有 SES 账号能直接搞定
  • 公司内刊 / 产品更新邮件:域名可控、API/MCP 可集成到产品里
  • AI 自动化营销:agent 通过 MCP 直接撰写 + 调度 + 发送 newsletter
  • 多刊团队:一个账号最多 3 个 newsletter,适合产品矩阵
  • 隐私 / 合规自托管:全部数据在自己 MongoDB,无第三方平台

5. 坑与注意

  1. "No support" 是产品定位,不是 bug。README 第一屏大字声明:"Issues are off, and setup questions go unanswered." 选型前必须接受"自己读文档 + 自己 fork"。
  2. AGPL-3.0 协议:对外提供服务的衍生版本必须开源——SaaS 改造前先看 LICENSE,商业 fork 涉及法务。
  3. 默认发送被关——首次部署后,必须接着配 SES 或 PostShiba + DNS + 等批生产权限,不然连你自己都发不出去。
  4. Vercel 没有固定 IP:MongoDB Atlas 的 Network Access 必须 allow 0.0.0.0/0,否则连不上;这跟"静态 IP 安全白名单"思路不兼容。
  5. 没 Redis = rate limit 不跨实例共享:无 Redis 时,serverless 部署每次冷启都重置计数。接 signup 表单到繁忙页面前必须先加 Upstash Redis。
  6. 没 S3 / Blob = 不能上传图;HTML / Markdown 邮件引用外链图依然能用。
  7. PostShiba 目前仅邀请制,自托管用户首选还是 SES;SES 沙盒首日仅 200 封 + 必须验证收件人,要生产发请早申请批生产权限。
  8. API key 不放大配额:这是反爬虫 / 反滥用的设计,但自动化集成方需要预估 rate,提前申请扩额。
  9. APP_URL 影响所有邮件里的链接(直到 newsletter 自己的 archive 子域生效),第一次发送前必须设对,改一次就废一批邮件。
  10. AWS SES 推荐单租户账号:SES reputation / 限额是 per AWS account,别跟其它业务共用。
  11. Cloud 模式部署 ≠ 自托管:虽然跑同一份代码,但 MAILCHEAP_CLOUD=true 会启用 Stripe 计费 / 计划 / 我们自己的发件账号——自己跑留 false,别打开。
  12. marketing site 不开源:README 明示landing / pricing / legal 页不在开源里,别 fork 后改这些页(就是 README 公开警告的边界)。
  13. 删除账号 30 天后真删——这是 GDPR / privacy 设计,但用户没看清就删会救不回来,运营流程要写进 onboarding。
  14. Mailcheap.ai 的 SLA、定价细则 README 没列,打算用 Cloud 必须去官网单独查。

6. 与同类对比

平台 自托管 价格模型 Agent / API 多刊 退信防护 协议
MailCheap ✅ 自托管 = 仅付 SES / PostShiba 发件成本;Cloud $19+/月 ✅ REST + MCP(原生) 1 账号 3 刊 内置 2% / 0.08% 自动暂停 AGPL-3.0
Substack ❌ 抽成 10% ❌ 1 基础 闭源
Beehiiv ❌ 阶梯订阅 有限 API 多 基础 闭源
ConvertKit ❌ 按订阅 Zapier 集成 多 基础 闭源
Ghost(自托管 newsletter) ✅ 自己付 SES REST / Webhooks 多 需配置 MIT
Listmonk ✅ 自己付 SMTP REST 多 基础 + 自配 AGPL-3.0

MailCheap 独特定位:原生 MCP server + 内置阶梯发送 + bounce/complaint 自动暂停。对 AI 工作流友好的程度在 newsletter 圈独一档。

7. 一句话推荐

你的 newsletter 要走 AI 自动化 + 自托管 + 不想被平台抽成,接 SES 就能 5 分钟上线——MailCheap 是当下唯一原生 MCP + 内置发件防护的选项;但必须接受"No support / 自己读文档 / AGPL-3.0"这三个边界。

8. 资源链接

  • 仓库:https://github.com/marclou/mailcheap
  • Cloud 版:https://mailcheap.ai
  • Vercel 一键部署:README 内的 vercel.com/new/clone?... 链接
  • 自托管文档:README 主体(无独立 docs 站)
  • REST API:/api/v1(同仓库)
  • MCP server:/mcp(同仓库)
  • 截图:docs/screenshots/(overview / editor / report / contacts / archive / issue)
  • 配套服务:MongoDB Atlas、AWS SES、PostShiba、Upstash QStash、Upstash Redis、Vercel Blob、AWS S3 + CloudFront、Resend