内容
# dispatch 📨
> 开源、可自行托管、适用于智能代理的电子邮件营销平台。
dispatch 是一个 AGPL-3.0 许可的 Mailchimp 替代品，从头设计用于自行托管和智能代理作为一类操作符。目前处于 **M1** 里程碑：首次安全发送。`/v1` API 涵盖联系人、列表、同意（包括双重确认：公开订阅 → 确认电子邮件 → 单次确认）、抑制、继电器（SES v2、Resend、SMTP）、发件人身份、模板、活动（检查 → 预览 → 准备 → 确认令牌 → 发送）、提供商 webhook 收件箱、RFC 8058 一键退订、打开/点击跟踪（像素 + 重定向链接，按联系人选择退出）、统计数据和审计事件。工作进程运行由发送队列支持的发送管道，并进行每次发送的同意重新检查和自动暂停弹跳/投诉。
## 快速开始
先决条件：Node 24（>= 22 在本地有效），pnpm 10，Docker。
```bash
# 启动 PostgreSQL 和 Redis
docker compose -f docker/docker-compose.yml up -d postgres redis
# 配置环境（完整模式参见 packages/config）
export APP_URL=http://localhost:3000 \
PUBLIC_URL=http://localhost:3000 \
TRACKING_URL=http://localhost:3000 \
DATABASE_URL=postgres://dispatch:dispatch@localhost:5432/dispatch \
REDIS_URL=redis://localhost:6379 \
CREDENTIAL_ENCRYPTION_KEY=$(openssl rand -hex 32) \
SESSION_SECRET=$(openssl rand -hex 32)
pnpm install
pnpm build
pnpm --filter @dispatch/db migrate # 应用数据库迁移
pnpm --filter @dispatch/api bootstrap "我的工作空间" "我的组织有限公司" "1 主街"
pnpm dev # API 在 :3000，网页在 :5173，工作进程
```
引导命令仅一次打印所有者 API 密钥；请存储它。所有 `/v1` 调用均通过 `Authorization: Bearer dk_...` 进行身份验证。
测试在没有 Docker 的情况下运行（PGlite 进程内 PostgreSQL）。基于 Testcontainers 的套件在存在 Docker 守护进程并设置 `DISPATCH_DOCKER_TESTS=1` 时额外运行。
通过 `docker compose -f docker/docker-compose.yml up --build app` 提供了一个全功能的容器（API + 工作进程 + 网页静态包）。镜像内部运行 `pnpm build`，因此不需要本地构建产物。
## 仓库布局
```
apps/
api/ Hono REST API 在 /v1 下，OpenAPI，API 密钥身份验证，公共路由
mcp/ MCP 服务器（stdio）将 /v1 接口暴露给代理
web/ Vite + React 19 控制界面（存根）
worker/ BullMQ 工作进程：发送管道，webhook 规范化，调度器
packages/
config/ Zod 验证环境配置，快速失败
db/ Drizzle ORM 模式，迁移，存储库（PostgreSQL 16）
domain/ 状态机，同意决策，令牌，合并标签，重试
contracts/ API 约定：RFC 9457 问题详情，游标分页
relays/ RelayProvider 合同 + SES v2 / Resend / SMTP 驱动
render/ React Email 设计文档 → HTML/文本工件（ADR-0002）
queue/ 作业合同，发送队列调度器，速率限制器
testkit/ 假继电器，控制时钟
docker/ 用于本地开发和一体化镜像的 docker-compose
docs/adr/ 架构决策记录
```
## 与 AI 代理一起使用
dispatch 正在构建代理原生功能：UI 暴露的每个操作也可通过自动化访问。 一级 MCP 服务器（`apps/mcp`）通过 stdio 暴露 `/v1` 接口：
```json
{
"mcpServers": {
"dispatch": {
"command": "node",
"args": ["apps/mcp/dist/index.js"],
"env": { "DISPATCH_API_URL": "http://localhost:3000", "DISPATCH_API_KEY": "dk_..." }
}
}
}
```
发送故意不作为 MCP 工具：代理草稿和预览，确认发送保留在单次确认流程后。
## 文档
- [架构决策记录](docs/adr/)
- [贡献](CONTRIBUTING.md)
- [安全政策](SECURITY.md)
## 许可证
[AGPL-3.0](LICENSE). 查看 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
