jdrouet/catapulte

Catapulte 镜像文档

镜像概述

Catapulte 是一款开源的自托管邮件发送器，旨在帮助用户快速、可靠地发送事务性邮件。它支持 MJML 模板渲染、动态数据插值，并通过连接 SMTP 服务器实现邮件投递。作为自托管解决方案，用户可完全掌控邮件发送流程和数据隐私，避免依赖第三方邮件服务的限制。

核心功能与特性

事务性邮件优化

专注于事务性邮件场景，解决传统邮件服务投递延迟问题，确保登录验证、通知等关键邮件快速送达。

自托管与本地部署

支持本地部署，满足企业内部网络环境或数据合规要求，无需依赖外部服务，避免网络代理限制。

数据隐私保护

无需将用户邮件数据提交给第三方服务，规避美国《爱国者法案》等***带来的数据访问风险，确保用户数据安全。

灵活模板管理

提供 MJML 模板支持，非技术人员可直接编辑邮件模板，减少开发团队频繁修改模板的工作量。

多场景适配

支持连接各类 SMTP 服务器（如本地服务器、Amazon SES 等），可通过环境变量灵活配置认证方式和传输加密。

使用场景

创业公司

• 成本敏感：无需支付第三方邮件服务费用，可使用自有 SMTP 服务器或低成本服务（如 Amazon SES）
• 效率需求：快速响应模板修改需求，让产品团队自主管理邮件内容
• 定制化：支持功能扩展，可通过代码贡献添加特定功能

大型企业

• 数据合规：满足内部数据不外流要求，避免用户数据存储在外部服务
• 网络限制：适应企业内网环境，可部署在受限网络中
• 定制认证：支持自定义 SMTP 认证方式，适配企业现有邮件基础设施

使用方法

快速启动（Docker）

推荐使用 Docker 部署，支持 amd64、i386 和 arm64v8 架构。以下命令可启动基础服务：

bash
docker run -d \
  --name catapulte \
  -e SMTP_HOSTNAME=localhost \
  -e SMTP_PORT=25 \
  -e SMTP_USERNAME=optional \
  -e SMTP_PASSWORD=optional \
  -e SMTP_TLS_ENABLED=true \
  -e SWAGGER_ENABLED=true \
  -e TEMPLATE_PROVIDER=local \
  -e TEMPLATE_ROOT=/templates \
  -p 3000:3000 \
  -v /path/to/your/templates:/templates:ro \
  jdrouet/catapulte:master

环境变量配置

发送邮件示例

基本文本邮件（JSON 格式）

bash
curl -X POST -v \
  -H "Content-Type: application/json" \
  --data '{"from":"alice@example.com","to":"bob@example.com","params":{"some":"data"}}' \
  http://localhost:3000/templates/the-name-of-your-template

带附件的邮件（multipart 格式）

bash
curl -X POST -v \
  -F attachments=@asset/cat.jpg \
  -F from=alice@example.com \
  -F to=bob@example.com \
  -F params='{"some":"data"}' \
  http://localhost:3000/templates/user-login

多收件人邮件

通过数组形式指定多个收件人：

bash
curl -X POST -v \
  -H "Content-Type: application/json" \
  --data '{"from":"alice@example.com","to":["bob@example.com","jon@example.com"],"params":{"some":"data"}}' \
  http://localhost:3000/templates/the-name-of-your-template

模板管理

Catapulte 使用 MJML 模板进行邮件渲染。模板文件需放置在 TEMPLATE_ROOT 指定的目录下（通过 -v 挂载本地目录到容器内）。模板支持动态数据插值，具体格式可参考项目仓库的 /template 文件夹示例。

生产环境配置

对于生产环境，推荐结合 Amazon SES（Simple Email Service）使用，可参考项目文档中关于 AWS SES 集成的详细说明，以实现低成本、高可靠性的邮件投递。

API 文档

启用 SWAGGER_ENABLED=true 后，可通过访问 http://localhost:3000/swagger 查看 OpenAPI 规范的 API 文档，包含所有可用接口的详细说明。