Operate a self-hosted notifyd instance: digest, jobs, retries, suppressions, projects, test sends.
io.github.rmzlb/notifyd MCP Server
The io.github.rmzlb/notifyd MCP server operates a self-hosted notifyd instance focused on notifications. The description highlights digest handling, jobs, retries, suppressions, project organization, and test sends. It is positioned as an “agent-first notification service,” implemented as a single Rust binary using Postgres only.
🛠️ Key Features
Digest support
Jobs and retry handling
Suppressions
Projects
Test sends
🚀 Use Cases
Running a self-hosted notification service
Sending and testing notification delivery flows
Managing notification suppression and digests
Orchestrating job execution with retries
⚡ Developer Benefits
Single Rust binary deployment
Postgres-only dependency model
MCP integration via model-context-protocol
Uses tags including Rust, Axum, and email/push/SMS topics
⚠️ Limitations
The readme excerpt indicates Postgres only; no Redis or Mongo is referenced.
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.
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.
code
┌───────────────────────────── 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 ──────────────────────────┘
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.
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"
}'
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):
bash
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 you@example.com
NOTIFYD_URL=https://notifyd.example.com NOTIFYD_ADMIN_API_KEY=… notifyd digest # from your laptop
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:
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. 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):
bash
npx skills add rmzlb/notifyd
Published on the official MCP registry as mcp-name: io.github.rmzlb/notifyd
(server.json). Full operator guide: docs/AGENT.md.
Priorities — critical, normal, bulk lanes; /v1/batch and campaign tags land in bulk
Pacing — token bucket per channel (EMAIL_RATE_PER_SEC); a provider 429 pauses that channel for Retry-After without consuming an attempt, other channels keep flowing, and when it resumes the claim order puts critical first
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 — batch to "plan = pro and country in FR, BE" with a small filter vocabulary compiled to bound SQL; preview the count first
Unsubscribe — RFC 8058 List-Unsubscribe one-click on every marketing email, suppression scopes all / marketing
Topics and preferences — a topic on 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
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_at on 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.
Prebuilt image, linux/amd64 and linux/arm64: ghcr.io/rmzlb/notifyd.
Binary, crate, Nix or source
bash
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
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.
→ 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.
Method
Endpoint
What it does
POST
/v1/send
Send on one or several channels
POST
/v1/batch
Send to a list of subscribers or to a segment filter (bulk lane, idempotent)
POST
/v1/segments/preview
Count and sample the subscribers a segment matches
GET
/v1/jobs/:id
Status, provider, attempts, last error
GET
/v1/inbox/:id · /stream
In-app inbox, SSE realtime stream
POST
/v1/workflows/trigger
Trigger an event-based workflow
GET
/v1/admin/digest
What needs attention, with actions
GET
/v1/admin/jobs · /:id · POST …/:id/retry · /admin/send-test
Operator view and actions (also the CLI's transport)
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
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"])
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:
Variable
Purpose
EMAIL_PROVIDER
resend (default when RESEND_API_KEY is set), cloudflare, smtp, agentmail, log
EMAIL_FROM, EMAIL_FROM_NAME
Instance default sender; projects can override
EMAIL_FALLBACK_PROVIDER
Second provider on 429 / 5xx
EMAIL_RATE_PER_SEC
Outbound pacing per replica
SMS_PROVIDER, SMS_FROM
telnyx, twilio or smsmode with their credentials
PUBLIC_URL
Base URL for one-click unsubscribe links and Twilio and smsmode SMS delivery status
~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.
Issues and pull requests are welcome; good first issue is the place to
start, and big features begin with an issue. Read CONTRIBUTING.md.
bash
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