notifyd

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.

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

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

---

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

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 # provider, attempts, delivery events notifyd retry # 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:

# 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. The digest comes to you. DIGEST_NOTIFY=telegram: (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):

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, Twilio or smsmode, swap with one variable
• RCS — smsmode (BASIC / TEXT auto-selection, quick replies, click-to-call, rich cards and carousels)
• WhatsApp — Telnyx
• Push — APNs natively (.p8 token 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 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
• Segments — batch to "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-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

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_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

-