notifyd

notifyd

通过一次 API 调用发送电子邮件、SMS、WhatsApp、推送和应用内通知。
一个 12 MB 的 Rust 二进制文件，仅依赖 PostgreSQL。队列、重试、提供商故障切换和免打扰时段均由它处理，AI Agent 也可以通过 MCP 操作它。

快速开始 • 客户端 • 示例 • Agent 运维 • API 参考 • 架构 • 基准测试 • llms.txt • 参与贡献

---

它是什么

你的应用需要告诉人们一些事情：重置密码、包裹已发货、新闻简报，或角落里的红色徽标。notifyd 是一款小型服务，负责处理所有这些事情；你的代码只需调用一次，之后就不用再操心服务提供商、速率限制、重试或时区。

                 ┌───────────────────────────── notifyd ──────────────────────────────┐
your app ─────▶  │ POST /v1/send ─▶ queue ─▶ priority ─▶ pacing ─▶ retry ─▶ failover  │ ─▶ email · sms · whatsapp
                 │                                                                    │    push · in-app · telegram · slack · discord
your agent ───▶  │ POST /mcp ─▶ digest · jobs · retry · suppressions · settings       │
                 └───────────────────────── PostgreSQL only ──────────────────────────┘

• 小巧又快速。 一个 12 MB 的二进制文件，拉取的镜像为 14 MB，空闲时占用 13 MB RAM。在笔记本电脑上，它每秒可接收 44 000 条通知，每秒处理 3 500 条（测试方法）。无需 Redis、无需消息代理，也无需托管仪表板：唯一的依赖是 PostgreSQL。
• 消息绝不会丢失。 密码重置始终优先于营销活动。服务提供商提示“减速”时，该渠道会暂停指定的时长，然后按优先级顺序恢复；如果服务提供商发生故障，则由另一家接手。内置重试、幂等性，以及根据每位收件人所在时区设置的免打扰时段。
• 使用你自己的服务提供商，掌控自己的数据。 Resend、Cloudflare Email、任意 SMTP、AgentMail、Telnyx、Twilio、smsmode、APNs、Web Push、FCM。可自托管，采用 MIT 许可证。
• 通过 API 或 AI Agent 运维。 没有管理界面：摘要端点会说明哪些事项需要关注以及该如何处理；相同的操作也提供为 MCP 工具，因此值班人员可以由 Agent 担任。

目前有三个实例在生产环境中运行，每家公司各一个，均按这种方式运维。

_{60 秒介绍，使用虚构数据。MP4 · Remotion 源码}

---

一次调用即可发送

curl -X POST https://notifyd.example.com/v1/send \
  -H "X-Api-Key: sk_myapp_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channels": ["email", "in_app"],
    "subscriber_id": "user-1",
    "subject": "Your report is ready",
    "body": "Hey {{first_name}}, the analysis you requested is complete.",
    "vars": {"first_name": "Alice"},
    "priority": "normal",
    "idempotency_key": "report-42-ready"
  }'

纯 REST API，curl 即可使用；提供 TypeScript 和 Python 客户端。 重试是安全的（idempotency_key），调度通过字段设置 （scheduled_at）；营销活动可通过 POST /v1/batch 发起，每次调用可处理数千名 订阅者，并进入批量通道，因此绝不会延误密码重置邮件。每次发送后都可以调用 GET /v1/jobs/:id 查询状态。每种语言都提供可运行的示例：examples/。

---

在终端中运行

同一个二进制文件也是运维人员使用的 CLI，可连接任意实例（服务器主机的环境中 设有 ADMIN_API_KEY，因此在那里可以直接使用）：

notifyd digest                       # what needs attention, with the action for each finding
notifyd jobs --status failed         # --project, --channel, --topic, --recipient, --since 24h, --limit, --json
notifyd job <id>                     # provider, attempts, delivery events
notifyd retry <id>                   # re-queue after fixing the cause
notifyd send-test --project myapp --channel email --to [email protected]
NOTIFYD_URL=https://notifyd.example.com NOTIFYD_ADMIN_API_KEY=… notifyd digest   # from your laptop

---

让你的 Agent 来运行

大多数通知工具都是为人类通过仪表板点击操作而设计的。notifyd 将运维人员的工作作为工具提供，并包含人类运维人员所需的详细信息：

1. 一次调用即可指出需要关注的事项。 GET /v1/admin/digest 会对 问题进行排序，并以 JSON 或 Markdown 格式告知每项问题应采取的操作：

# notifyd digest — last 1d
Instance: commit e14e6f3, up 3d, email resend (+ smtp fallback), sms telnyx

## Findings
- **warning** — Primary email provider `resend` is resting for 47s after refusing messages; `smtp` is delivering.
  _Nothing lost. Check the primary provider's status page; if it repeats, lower EMAIL_RATE_PER_SEC or move the primary role to the other provider._
- **warning** — Bounce rate 5.3 % over the window (14 bounced / 263 delivered).
  _Above 5 % providers throttle or suspend the sender. Clean the recipient list; suppressions are applied automatically._
- **warning** — 3 job(s) failed in the last 1d (0.1 % of terminal jobs). Top cause: 422 unverified sender domain.
  _Inspect with list_jobs(status=failed); permanent errors need a fix on the caller side, then retry_job._

## Queue          pending 0, retry 2, processing 0
## Outcomes       email/resend 4 812 sent, 3 failed · in_app 1 203 sent
## Latency        email p50 0.6s, p95 2.1s (scheduled → accepted by provider)
## Deliverability delivered 4 790, bounced 14, complained 0, unsubscribed 9

2. 同样的操作也可作为 MCP 工具使用。 POST /mcp 是一个 Streamable HTTP MCP 服务（使用当前规范修订版，并保留旧版 initialize）。将其添加到 Claude Code、Claude Desktop、Cursor 或你自己的 Agent 中：

{ "mcpServers": { "notifyd": {
  "type": "http", "url": "https://notifyd.example.com/mcp",
  "headers": { "Authorization": "Bearer ${NOTIFYD_ADMIN_API_KEY}" } } } }

工具	Agent 可以执行的操作
digest	按项目列出排序后的问题及对应操作、队列、结果、延迟和送达情况
list_jobs、get_job	按项目、渠道、状态、收件人和时间筛选；查看服务提供商、尝试次数和上次错误
retry_job、cancel_job	处理卡住或发送错误的任务
list_projects、update_project	发件人身份（from_email、from_name）、渠道、入站速率限制，以及按收件人时区设置的批量 send_window
list_suppressions、add_suppression、release_suppression	查看抑制列表，可使用 all 或 marketing 范围
template_metrics	查看每个模板的已发送、失败、退回和已打开数量
send_test	在任意渠道端到端验证整个管道

每个工具都带有 readOnlyHint / destructiveHint 注释和 outputSchema。只读运维密钥（READONLY_API_KEY）仅开放读取工具，适用于 只负责报告、不应采取操作的 Agent。每次 MCP 调用都会记录审计日志。

3. 摘要会主动发送给你。 设置 DIGEST_NOTIFY=telegram:<chat id>（或 Slack / Discord webhook），当有事项需要关注时，上述问题就会发送到你的聊天中； 执行 notifyd digest --to telegram:… 可立即发送一次。

4. 仓库中包含 Agent 所需的一切集成资料。 docs/llms.txt 以纯文本形式提供完整 API，适合放入上下文窗口；skills/ 中附带三个 Agent Skills（notifyd-operate、notifyd-integrate、 notifyd-deploy）：

npx skills add rmzlb/notifyd

已在官方 MCP 注册表中发布，mcp-name: io.github.rmzlb/notifyd （server.json）。完整运维指南：docs/AGENT.md。

---

功能

渠道

• 电子邮件 — Resend、Cloudflare Email Service、AgentMail、任意 SMTP（lettre）、附件、每个项目的发件人身份
• 短信 — Telnyx、Twilio 或 smsmode，通过一个变量切换
• RCS — smsmode（自动选择 BASIC / TEXT、快速回复、点击呼叫、富媒体卡片和轮播）
• WhatsApp — Telnyx
• 推送 — 原生支持 APNs（.p8 令牌身份验证、HTTP/2、徽标、声音、线程 ID、静默推送、丢弃失效令牌）、Web Push（VAPID）、FCM
• 应用内收件箱 — REST + 实时 SSE（EventSource）、已读 / 归档 / 加星标、未读徽标，通过 Postgres NOTIFY 支持多副本

投递引擎

• 优先级 — critical、normal、bulk 通道；/v1/batch 和营销活动标签会进入 bulk
• 速率控制 — 每个渠道使用令牌桶（EMAIL_RATE_PER_SEC）；服务提供商返回 429 时，该渠道会按 Retry-After 暂停，且不消耗尝试次数；其他渠道继续运行，恢复后领取顺序会优先处理 critical
• 重试 — 30 秒 → 2 分钟 → 10 分钟 → 30 分钟 → 2 小时，并加入抖动；4xx 会快速失败；被拒绝的批次会逐项回退
• 故障转移 — 通过断路器切换到第二个电子邮件服务提供商（EMAIL_FALLBACK_PROVIDER）
• 发送时段 — 每个项目可设置静默时段，并根据每位订阅者的时区进行评估
• 分群 — 使用 batch 筛选“plan = pro and country in FR, BE”，通过简洁的筛选语法编译为绑定 SQL；可先预览数量
• 定时发送、幂等性、卡住任务回收、批次幂等性

治理

• 取消订阅 — 每封营销邮件都附带符合 RFC 8058 的 List-Unsubscribe 单击取消订阅功能，抑制范围为 all / marketing
• 主题和偏好设置 — 任何发送都可指定 topic（“tips”、“billing”）；订阅者可按主题和渠道选择退出，并在入队时生效；取消订阅页面会先提供“仅此主题”选项，再提供“所有营销邮件”选项
• 多项目 — 一个实例支持多个项目，通过 API 密钥隔离，并支持带宽限期的密钥轮换
• PII 脱敏（日志）、每次变更的审计日志、每个项目的速率限制

运维

• 摘要邮件、MCP 服务、Agent Skills、llms.txt
• 指标 — /v1/metrics、/v1/metrics/prometheus、每个模板的指标
• 打开和点击跟踪 — 为每个电子邮件服务提供商使用自有像素和签名重定向链接；默认用于营销邮件（交易邮件链接保持不变）；在任务上记录 opened_at / clicked_at，可按项目或请求关闭
• Webhook — 向你的端点发送投递事件
• 工作流 — 由事件触发的多步骤序列，状态存储在 Postgres 中
• 模板 — {{variable}} 替换，按项目存储

---

快速开始

Docker（推荐）

镜像从环境变量读取配置；无需挂载配置文件。

git clone https://github.com/rmzlb/notifyd.git && cd notifyd
cat > .env <<'EOF'
JWT_SECRET=change-me-32-random-chars-minimum
ADMIN_API_KEY=change-me-32-random-chars-minimum
RESEND_API_KEY=re_xxx
[email protected]
EOF
docker compose up -d          # notifyd + Postgres 16, http://localhost:3400

创建项目并获取其 API 密钥：

curl -s -X POST http://localhost:3400/v1/admin/projects \
  -H "X-Api-Key: $ADMIN_API_KEY" -H "Content-Type: application/json" \
  -d '{"id":"myapp","name":"My app","channels":["email","in_app"],"from_email":"[email protected]"}'
# → {"project": {"id": "myapp", "api_key": "sk_myapp_…", …}}

预构建镜像支持 linux/amd64 和 linux/arm64：ghcr.io/rmzlb/notifyd。

二进制文件、crate、Nix 或源代码

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/rmzlb/notifyd/releases/latest/download/notifyd-installer.sh | sh
brew install rmzlb/tap/notifyd             # macOS and Linux, Homebrew
cargo binstall notifyd                     # prebuilt from the GitHub release
cargo install notifyd                      # build from crates.io
nix run github:rmzlb/notifyd               # flake: packages, devShell, NixOS module
# then
DATABASE_URL=postgres://notifyd:pass@localhost:5432/notifyd \
JWT_SECRET=… ADMIN_API_KEY=… RESEND_API_KEY=… EMAIL_FROM=… notifyd

发布的二进制文件支持：Linux x86_64 和 aarch64、macOS Intel 和 Apple Silicon。 NixOS：设置 services.notifyd.enable = true;，并配置 environmentFile（参见 flake.nix）。

还没有配置服务提供商？EMAIL_PROVIDER=log 会打印电子邮件，而不是发送。

验证

curl http://localhost:3400/v1/health
# → {"status":"ok","db":"ok","version":"0.2.2","commit":"…","uptime_seconds":12}

→ 完整设置、TOML 替代方案和生产环境说明：docs/SETUP.md

---

API 一览

项目端点使用 X-Api-Key: sk_<project>_…；运维端点使用管理员（或只读）密钥，可通过 X-Api-Key 或 Authorization: Bearer 传入。 收件箱端点也接受订阅者 JWT。

方法	端点	功能
POST	/v1/send	通过一个或多个渠道发送
POST	/v1/batch	向订阅者列表或符合 segment 筛选条件的订阅者发送（批量通道，幂等）
POST	/v1/segments/preview	统计并抽样符合某个细分条件的订阅者
GET	/v1/jobs/:id	状态、提供商、尝试次数、上次错误
GET	/v1/inbox/:id · /stream	应用内收件箱、SSE 实时流
POST	/v1/workflows/trigger	触发基于事件的工作流
GET	/v1/admin/digest	需要关注的事项及相应操作
GET	/v1/admin/jobs · /:id · POST …/:id/retry · /admin/send-test	运维视图和操作（也是 CLI 的传输方式）
PATCH	/v1/admin/projects/:id	发件人、渠道、速率限制、发送时段
POST	/mcp	MCP 服务（Streamable HTTP）
GET	/v1/metrics/prometheus	Prometheus 指标格式
GET	/u/:token	一键取消订阅页面

→ 查看每个端点及其示例：docs/API.md，或将 docs/llms.txt 提供给你的 Agent。

---

与其他方案的比较

	Novu	Knock / Courier / SuprSend	notifyd
基础设施	MongoDB + Redis + 4 个应用容器	托管式 SaaS	仅需 Postgres，一个 14 MB 镜像
设置	30 分钟以上	注册 + 控制面板	docker compose up（2 分钟）
语言	Node.js（多个服务）	不适用（托管）	Rust（单个二进制文件）
空闲内存	6 个容器共 1.1 GB（实测）	不适用	13 MB；排空 100k 个任务时为 23 MB（方法）
需拉取的镜像	1.4 GB	不适用	14 MB
吞吐量	—	受配额限制	入队 44k 个任务/秒，排空 3.5k 个任务/秒（基准测试）
提供商返回 429	任务失败	托管处理	渠道暂停 Retry-After 指定的时间，不消耗尝试次数，并优先尝试故障转移提供商
优先级 / 发送时段	❌	✅	✅ 关键 → 批量通道，按订阅者时区设置时段
运维界面	React 控制面板	控制面板 + API	摘要端点、MCP 服务、Agent Skills、Prometheus
实时功能	WebSocket	WebSocket	SSE、原生 EventSource、多副本
可自托管	✅（资源开销大）	❌	✅ 每家公司一个容器
费用	免费层 / 付费	按通知计费	永久免费，MIT

此表中的所有数据均由我们实测得出；Novu 的数据来自其自己的社区版 docker-compose，在空闲状态下，于同一台机器上使用与我们相同的工具测得。测量方法、硬件和偏差免责声明见 docs/BENCHMARKS.md。

---

客户端

两个客户端都覆盖完整 API（发送、批量、任务、订阅者、偏好设置、模板、工作流、抑制列表、收件箱），并会针对任何非 2xx 响应抛出类型化错误。

TypeScript / JavaScript — 在本周 notifyd-sdk 包发布到 npm 前，使用 npm i github:rmzlb/notifyd；包名和下方的导入语句不会改变（Node 18+、浏览器、边缘运行时；零依赖）

import { createNotifydClient } from 'notifyd-sdk';

const notifyd = createNotifydClient({ url: process.env.NOTIFYD_URL!, apiKey: process.env.NOTIFYD_API_KEY! });

const { jobIds } = await notifyd.send({
  channels: ['email', 'in_app'], subscriberId: 'user-42',
  subject: 'Your order shipped', body: 'Hi {{first_name}}, parcel {{parcel}} is on its way.',
  vars: { first_name: 'Alice', parcel: 'FR-2041' }, idempotencyKey: 'order-2041-shipped',
});
const job = await notifyd.getJob(jobIds[0]);   // status, provider, attempts, delivery events

// Browser inbox: subscriber token from your backend, live updates over EventSource
const inbox = createNotifydClient({ url, subscriberToken });
const stream = await inbox.openInboxStream('user-42', { onMessage: (e) => {
  const event = JSON.parse(e.data);
  if (event.type === 'new_notification') showToast(event.notification);
  if (event.type === 'count_update') updateBadge(event.unread_count);
} });

Python — 在本周 notifyd-sdk 发布到 PyPI 前，使用 pip install "git+https://github.com/rmzlb/notifyd.git#subdirectory=clients/python"（3.9+、同步和 asyncio、仅需 httpx）—— clients/python

from notifyd import Notifyd

nd = Notifyd(os.environ["NOTIFYD_URL"], api_key=os.environ["NOTIFYD_API_KEY"])
result = nd.send(channels=["email", "in_app"], subscriber_id="user-42",
                 subject="Your order shipped", body="Hi {{first_name}}, parcel {{parcel}} is on its way.",
                 vars={"first_name": "Alice", "parcel": "FR-2041"}, idempotency_key="order-2041-shipped")
print(nd.get_job(result["job_ids"][0])["status"])

其他语言：API 使用扁平的 HTTP JSON 格式， docs/llms.txt 在一页中列出了完整契约。

---

工作流

由事件触发的多步骤序列，状态存储在 Postgres 中，可在重启后继续运行。各步骤按顺序执行；满足条件时会跳转到指定的步骤索引。

curl -X POST http://localhost:3400/v1/workflows -H "X-Api-Key: sk_myapp_xxx" -d '{
  "id": "welcome-series", "name": "Welcome series", "trigger_event": "user.signup",
  "steps": [
    {"type": "send", "channel": "email", "template": "welcome"},
    {"type": "delay", "duration_secs": 86400},
    {"type": "condition", "field": "payload.plan", "operator": "eq", "value": "pro", "on_true": 4},
    {"type": "send", "channel": "email", "template": "nudge"}
  ]}'

curl -X POST http://localhost:3400/v1/workflows/trigger -H "X-Api-Key: sk_myapp_xxx" \
  -d '{"event": "user.signup", "subscriber_id": "user-42", "payload": {"plan": "free"}}'

步骤类型：send、delay、condition（inbox.is_read 或 payload.<key>） 以及 digest（收集一段时间内的事件，然后发送一条消息）。完整脚本：examples/welcome-series.sh。

---

配置

环境变量是主要的配置接口（镜像和 compose 文件都使用环境变量）；本地开发也支持 notifyd.toml。 必需变量：DATABASE_URL、JWT_SECRET、ADMIN_API_KEY。此外还需配置一种提供商：

变量	用途
EMAIL_PROVIDER	resend（设置 RESEND_API_KEY 时为默认值）、cloudflare、smtp、agentmail、log
EMAIL_FROM、EMAIL_FROM_NAME	实例的默认发件人；项目可以覆盖
EMAIL_FALLBACK_PROVIDER	遇到 429 / 5xx 时使用的备用提供商
EMAIL_RATE_PER_SEC	每个副本的出站速率限制
SMS_PROVIDER、SMS_FROM	使用相应凭据的 telnyx、twilio 或 smsmode
PUBLIC_URL	单击即可退订的链接，以及 Twilio 和 smsmode 短信送达状态所用的基础 URL
READONLY_API_KEY	可选的只读运维密钥

→ 所有变量及各提供商的配置：docs/CONNECTORS.md 和 docker-compose.yml。TOML 参考： notifyd.toml.example。

---

架构

                 ┌──────────────────────── notifyd (one binary) ───────────────────────┐
 HTTP /v1, /mcp ─▶ axum API ─▶ jobs table ─▶ worker: claim (SKIP LOCKED, by priority) │
                 │                              ├─ pacer per channel, channel pause on 429│
                 │                              ├─ connectors (email/sms/whatsapp/push/in-app)
                 │                              ├─ failover breaker, retries, reaper      │
                 │                              └─ webhooks, metrics, audit               │
                 │  SSE hub ◀── Postgres NOTIFY ── (any replica)                          │
                 └───────────────────────────────┬──────────────────────────────────────┘
                                                 ▼
                                           PostgreSQL 16

src/
├── api/              # routes: send, batch, jobs, inbox, subscribers, templates, workflows, webhooks, admin ops, health
├── connectors/       # email (resend, cloudflare, smtp, agentmail, log), sms, whatsapp, push, in_app
├── worker.rs         # claim by priority, batch context, finalize, retries, failover
├── pacing.rs         # token buckets and channel pauses
├── failover.rs       # provider circuit breaker
├── ops.rs            # digest, findings, operator actions
├── mcp.rs            # MCP server (tools, annotations, audit)
├── send_window.rs    # quiet hours in the subscriber's timezone
├── unsubscribe.rs    # List-Unsubscribe tokens and landing
├── sse.rs            # inbox stream, Postgres NOTIFY fan-out
├── workflow_engine.rs, templates.rs, webhooks.rs, deliverability.rs, metrics.rs, pii.rs, middleware.rs
migrations/           # SQL, applied at start-up
skills/               # Agent Skills: operate, integrate, deploy
server.json           # MCP registry entry
flake.nix             # Nix package, devShell, NixOS module
dist-workspace.toml   # cargo-dist: release binaries and installer

约 14 000 行 Rust 代码，不含 unsafe。二进制文件为 12 MB（镜像中静态 musl 版本为 16 MB），拉取镜像需 14 MB，占用磁盘空间 31 MB；空闲时 RSS 为 13 MB，排空 100 000 个任务时为 23 MB。→ docs/ARCHITECTURE.md

---

状态

notifyd 是一个 0.x 版本，已在三家公司投入生产使用。尚未完成的内容： Swift 和 Kotlin 包；按设计不提供仪表板、A/B 测试或入站邮件。路线图中的顺序和规模见 docs/ROADMAP.md。破坏性变更会在发行说明中公布；队列架构会自动迁移。

---

文档

📦 设置	本地开发、Docker、生产环境
🧪 示例	curl、TypeScript、Python、10k 活动、工作流、浏览器收件箱、MCP 配置
🐍 Python 客户端 · TypeScript 客户端	完整 API 客户端、类型化错误、契约测试
🔌 API 参考	每个端点均附有 curl / TypeScript / Rust 示例
🤝 Agent 运维	摘要、MCP 工具、只读密钥、Agent 如何运行实例
🔌 连接器	提供商、环境变量、如何添加提供商
🏗️ 架构	队列、优先级、速率限制、SSE、连接器
📈 基准测试	资源占用、吞吐量、如何复现
🚀 部署	每家公司一个实例、运维手册
📝 文章	仅使用 PostgreSQL 构建通知队列：SKIP LOCKED 无法为你提供什么
🗺️ 路线图	后续计划、顺序和规模；明确不在计划中的内容
📣 曝光渠道	注册目录和发布渠道
🤖 llms.txt	面向 Agent 的纯文本 API 说明

---

参与贡献

欢迎提交问题和拉取请求；可以从 good first issue 开始，大型功能则应先提交问题。请阅读 CONTRIBUTING.md。

git clone https://github.com/YOUR_USERNAME/notifyd.git && cd notifyd
cargo test && EMAIL_PROVIDER=log DATABASE_URL=… JWT_SECRET=dev ADMIN_API_KEY=dev cargo run

许可证

MIT。

以 🦀 为引擎，构建于法国格勒诺布尔 🏔️