
notifyd
io.github.rmzlb由 GitHub 帳號 rmzlb 發布v0.4.0更新於 Nov 2, 2026
Operate a self-hosted notifyd instance: digest, jobs, retries, suppressions, projects, test sends.
概覽
透過 MCP 維運自架的 notifyd 通知伺服器:查看摘要、檢查與重試任務、管理專案、抑制名單和測試發送。
- 可以做什麼
- 讀取維運摘要,含依專案排序的問題項目、佇列、投遞結果、延遲與送達率
- 依專案、通道、狀態、收件者或時間列出並檢視任務,含供應商、嘗試次數與最後錯誤
- 重試或取消卡住或送錯的任務
- 列出並更新專案:寄件者身分、通道、進站速率限制與大量發送時段
- 列出、新增與解除抑制項目,範圍為全部或僅行銷
- 檢視依範本統計的指標,並在任一通道發送測試訊息
- 適用情境
- 適合自行運行 notifyd 執行個體的團隊,讓助理監控投遞狀況並採取行動:排查失敗任務、查看退信率、調整寄件者設定或驗證某個通道可用。在沒有管理後台、值班人員由代理擔任時特別有用。
- 執行需求
- 需要一個可透過 HTTP 存取的執行中 notifyd 執行個體,唯一相依元件是 PostgreSQL。MCP 端點為執行個體的 /mcp 路徑,需要 Authorization 的 bearer 權杖:管理員金鑰擁有完整權限,唯讀維運金鑰只開放讀取工具。伺服器本身需要 DATABASE_URL、JWT_SECRET 與 ADMIN_API_KEY,並至少設定一個供應商才能真正投遞訊息。
安裝
在 SourceWeft 中
- 開啟 儀表板中的 notifyd,將其新增到工作區。
- 連接 Authorization token 憑證。它們會被私密儲存,絕不會在公開頁面上展示。
- 為需要使用其工具的對話啟用該服務。
Web executable,透過 Streamable HTTP。 遠端服務在工作區中設定後即可從網頁執行環境執行。
其他 MCP 客戶端
參照 儲存庫 中的啟動說明。
README
notifyd
Send email, SMS, WhatsApp, push and in-app notifications from one API call.
One 12 MB Rust binary, PostgreSQL only. Queues, retries, provider failover and quiet hours are handled for you, and an AI agent can run it over MCP.
[License] [Container image] [crates.io] [CI] [Image size] [Memory] [MCP registry] [Agent Skills]
Quick Start • Clients • Examples • Agent operations • API Reference • Architecture • Benchmarks • llms.txt • Contributing
What it is
Your app has to tell people things: a password reset, a shipped parcel, a newsletter, a red badge in the corner. notifyd is the small server that does all of it, so your code makes one call and never has to think about providers, rate limits, retries or time zones again.
- Small and fast. One 12 MB binary, a 14 MB image to pull, 13 MB of RAM idle. It accepts 44 000 notifications per second and drains 3 500 per second on a laptop (method). No Redis, no message broker, no dashboard to host: PostgreSQL is the only dependency.
- Nothing gets lost. A password reset always goes before a campaign. When a provider says "slow down", that channel pauses for exactly the time asked and resumes in priority order; when it fails, a second provider takes over. Retries, idempotency and quiet hours in each recipient's time zone are built in.
- Your providers, your data. Resend, Cloudflare Email, any SMTP, AgentMail, Telnyx, Twilio, smsmode, APNs, Web Push, FCM. Self-hosted, MIT.
- Operated by an API or an AI agent. No admin UI: a digest endpoint says what needs attention and what to do, and the same operations are MCP tools, so the person on call can be an agent.
Three instances run in production today, one per company, operated this way.
[60-second explainer: one send call, priority order under a provider 429, an agent operating the instance over MCP]
60 s explainer, invented data. MP4 · Remotion source
Send in one call
Flat REST, curl works; TypeScript and Python clients
exist. Retries are safe (idempotency_key), scheduling is a field
(scheduled_at), a marketing campaign is POST /v1/batch with thousands of
subscribers per call and it lands in the bulk lane so it never delays a
password reset. Follow any send with GET /v1/jobs/:id. Runnable examples in
every language: examples/.
Run it from a terminal
The same binary is the operator's CLI, against any instance (the server host
has ADMIN_API_KEY in its environment, so it just works there):
Let your agent run it
Most notification tools were designed for a human clicking through a dashboard. notifyd exposes the operator's job as tools, with the detail a human operator would need:
1. One call says what needs attention. GET /v1/admin/digest ranks
findings and tells you the action for each one, in JSON or Markdown:
2. The same operations as MCP tools. POST /mcp is a Streamable HTTP
MCP server (current spec revision, legacy initialize kept). Add it to Claude
Code, Claude Desktop, Cursor or your own agent:
Every tool carries readOnlyHint / destructiveHint annotations and an
outputSchema. A read-only operator key (READONLY_API_KEY) exposes only
the read tools, for an agent that reports but must not act. Every MCP call is
audited.
3. The digest comes to you. DIGEST_NOTIFY=telegram:<chat id> (or a
Slack / Discord webhook) and the findings above land in your chat when
something needs attention; notifyd digest --to telegram:… sends one now.
4. Everything an agent needs to integrate is in the repo. docs/llms.txt
is the whole API in plain text for a context window; three Agent Skills
ship in skills/ (notifyd-operate, notifyd-integrate,
notifyd-deploy):
Published on the official MCP registry as mcp-name: io.github.rmzlb/notifyd
(server.json). Full operator guide: docs/AGENT.md.
Features
Channels
- Email — Resend, Cloudflare Email Service, AgentMail, any SMTP (
lettre), attachments, per-project sender identity - SMS — Telnyx, Twilio or smsmode, swap with one variable
- RCS — smsmode (
BASIC/TEXTauto-selection, quick replies, click-to-call, rich cards and carousels) - WhatsApp — Telnyx
- Push — APNs natively (
.p8token auth, HTTP/2, badge, sound, thread id, silent pushes, dead tokens dropped), Web Push (VAPID), FCM - In-app inbox — REST + realtime SSE (
EventSource), read / archive / star, unread badge, multi-replica through PostgresNOTIFY
Delivery engine
- Priorities —
critical,normal,bulklanes;/v1/batchand campaign tags land inbulk - Pacing — token bucket per channel (
EMAIL_RATE_PER_SEC); a provider 429 pauses that channel forRetry-Afterwithout consuming an attempt, other channels keep flowing, and when it resumes the claim order putscriticalfirst - Retries — 30 s → 2 m → 10 m → 30 m → 2 h with jitter, 4xx fail fast, rejected batches fall back item by item
- Failover — second email provider with a circuit breaker (
EMAIL_FALLBACK_PROVIDER) - Send windows — quiet hours per project, evaluated in each subscriber's timezone
- Segments —
batchto "plan = pro and country in FR, BE" with a small filter vocabulary compiled to bound SQL; preview the count first - Scheduling, idempotency, stuck-job reaper, batch idempotency
Governance
- Unsubscribe — RFC 8058
List-Unsubscribeone-click on every marketing email, suppression scopesall/marketing - Topics and preferences — a
topicon any send ("tips", "billing"); subscribers opt out per topic and channel, honoured at enqueue; the unsubscribe page offers "this topic only" before "all marketing" - Multi-project — one instance, many projects, isolated by API key, key rotation with a grace period
- PII masking in logs, audit log of every mutation, per-project rate limit
Operations
- Digest, MCP server, Agent Skills,
llms.txt - Metrics —
/v1/metrics,/v1/metrics/prometheus, per-template metrics - Open and click tracking — own pixel and signed redirect links for every email provider, on marketing email by default (transactional links stay untouched),
opened_at/clicked_aton the job, off per project or per request - Webhooks — delivery events to your endpoints
- Workflows — event-triggered multi-step sequences, state in Postgres
- Templates —
{{variable}}substitution, stored per project
Quick Start
Docker (recommended)
The image reads its configuration from environment variables; no config file to mount.
Create a project and get its API key:
Prebuilt image, linux/amd64 and linux/arm64: ghcr.io/rmzlb/notifyd.
Binary, crate, Nix or source
Release binaries: Linux x86_64 and aarch64, macOS Intel and Apple Silicon.
NixOS: services.notifyd.enable = true; with an environmentFile (see
flake.nix).
No provider yet? EMAIL_PROVIDER=log prints emails instead of sending them.
Verify
→ Full setup, TOML alternative, production notes: docs/SETUP.md
API at a glance
Project endpoints take X-Api-Key: sk_<project>_…; operator endpoints take
the admin (or read-only) key, as X-Api-Key or Authorization: Bearer.
Inbox endpoints also accept a subscriber JWT.
→ Every endpoint with examples: docs/API.md, or feed docs/llms.txt to your agent.
vs. the alternatives
Every number in this table was measured by us; the Novu figures come from its own community docker-compose, idle, on the same machine and with the same tool as ours. Method, hardware and bias disclaimer in docs/BENCHMARKS.md.
Clients
Both clients cover the whole API (send, batch, jobs, subscribers, preferences, templates, workflows, suppressions, inbox) and raise a typed error on any non-2xx answer.
TypeScript / JavaScript — npm i github:rmzlb/notifyd until the notifyd-sdk package lands on npm this week; the package name and the import below do not change (Node 18+, browsers, edge runtimes; zero dependencies)
Python — pip install "git+https://github.com/rmzlb/notifyd.git#subdirectory=clients/python" until notifyd-sdk lands on PyPI this week (3.9+, sync and asyncio, httpx only) — clients/python
Any other language: the API is flat JSON over HTTP and docs/llms.txt is the whole contract on one page.
Workflows
Multi-step sequences triggered by an event, state in Postgres, survive restarts. Steps run in order; a condition jumps to a step index.
Step types: send, delay, condition (inbox.is_read or payload.<key>)
and digest (collect events for a while, then send one message). Full
script: examples/welcome-series.sh.
Configuration
Environment variables are the primary interface (that is what the image and
the compose file use); a notifyd.toml is accepted for local development.
Required: DATABASE_URL, JWT_SECRET, ADMIN_API_KEY. Then one provider:
→ Every variable, per provider: docs/CONNECTORS.md and docker-compose.yml. TOML reference: notifyd.toml.example.
Architecture
~14 000 lines of Rust, no unsafe. 12 MB binary (16 MB static musl in the image), 14 MB image to pull and 31 MB on disk, 13 MB RSS
idle, 23 MB while draining 100 000 jobs. → docs/ARCHITECTURE.md
Status
notifyd is a 0.x running in production for three companies. Not done yet: Swift and Kotlin packages; no dashboard, A/B testing or inbound email by design. Order and sizes in docs/ROADMAP.md. Breaking changes are announced in release notes; the queue schema is migrated automatically.
Documentation
Contributing
Issues and pull requests are welcome; good first issue is the place to
start, and big features begin with an issue. Read CONTRIBUTING.md.
License
MIT.
Built with 🦀 in Grenoble, France 🏔️
來源:README.md,提交 3239a54
工具
0版本歷史
1- v0.4.0最新Sep 16, 2026
評分
已滿足適用檢查項的 60%
該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。
- 近 30 天內可連通必需25 分
請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。
- 已宣告認證方式必需10 分
- 已列出工具15 分
請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。
- 描述必需15 分
- 圖示10 分
- 文件15 分
- 授權條款10 分