notifyd

Send email, SMS, WhatsApp, push and in-app notifications from one API call.
One 10 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.

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.

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

• Small and fast. One 10 MB binary, a 42 MB image, 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, 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 s explainer, invented data. MP4 · Remotion source}

Send in one call

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/.

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:

# 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:

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

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. 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):

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.

Features

Channels

• Email — Resend, Cloudflare Email Service, AgentMail, any SMTP (lettre), attachments, per-project sender identity
• SMS — Telnyx or Twilio, swap with one variable
• WhatsApp — Telnyx
• Push — Web Push (VAPID) or FCM
• In-app inbox — REST + realtime SSE (EventSource), read / archive / star, unread badge, multi-replica through Postgres NOTIFY

Delivery engine

• 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
• Scheduling, idempotency, stuck-job reaper, batch idempotency

Governance

• Unsubscribe — RFC 8058 List-Unsubscribe one-click on every marketing email, suppression scopes all / marketing
• Preferences — per-subscriber opt-in / opt-out
• 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
• 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.

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

Create a project and get its API key:

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_…", …}}

Prebuilt image, linux/amd64 and linux/arm64: ghcr.io/rmzlb/notifyd.

Binary, crate, Nix or source

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.

Verify

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

→ 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

We only publish numbers we measured on notifyd itself; the rest of the table
describes shape, not performance. 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 notifyd-sdk (Node 18+, browsers, edge runtimes; zero dependencies)

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 — pip install notifyd-sdk (3.9+, sync and asyncio, httpx only) — 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"])

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.

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"}}'

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

                 ┌──────────────────────── 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

~12 000 lines of Rust, no unsafe. 10.8 MB binary, 42 MB image, 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. What it does not
do yet: native APNs (Web Push and FCM today), topic-level preferences,
segments, own open tracking; 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.

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

License

MIT.

Built with 🦀 in Grenoble, France 🏔️