notifyd

<p align="center">
  <img src="docs/assets/notifyd-logo.svg" alt="notifyd" width="96" />
</p>

<h1 align="center">notifyd</h1>

<p align="center">
  <strong>Send email, SMS, WhatsApp, push and in-app notifications from one API call.</strong><br>
  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.
</p>

<p align="center">
  <a href="https://github.com/rmzlb/notifyd/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License"></a>
  <a href="https://github.com/rmzlb/notifyd/pkgs/container/notifyd"><img src="https://img.shields.io/badge/ghcr.io-rmzlb%2Fnotifyd-2496ED?style=flat-square&logo=docker&logoColor=white" alt="Container image"></a>
  <a href="https://crates.io/crates/notifyd"><img src="https://img.shields.io/crates/v/notifyd?style=flat-square&logo=rust" alt="crates.io"></a>
  <a href="https://github.com/rmzlb/notifyd/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/rmzlb/notifyd/ci.yml?branch=main&style=flat-square&label=ci" alt="CI"></a>
  <img src="https://img.shields.io/badge/image-44_MB-green?style=flat-square" alt="Image size">
  <img src="https://img.shields.io/badge/RSS-13_MB_idle-green?style=flat-square" alt="Memory">
  <a href="https://registry.modelcontextprotocol.io/v0/servers?search=notifyd"><img src="https://img.shields.io/badge/MCP_registry-io.github.rmzlb%2Fnotifyd-8A2BE2?style=flat-square" alt="MCP registry"></a>
  <a href="https://skills.sh/rmzlb/notifyd"><img src="https://skills.sh/b/rmzlb/notifyd" alt="Agent Skills"></a>
</p>

<p align="center">
  <a href="#quick-start">Quick Start</a> •
  <a href="#clients">Clients</a> •
  <a href="examples/">Examples</a> •
  <a href="#let-your-agent-run-it">Agent operations</a> •
  <a href="docs/API.md">API Reference</a> •
  <a href="docs/ARCHITECTURE.md">Architecture</a> •
  <a href="docs/BENCHMARKS.md">Benchmarks</a> •
  <a href="docs/llms.txt">llms.txt</a> •
  <a href="CONTRIBUTING.md">Contributing</a>
</p>

---

## 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 44 MB image, 13 MB of RAM idle. It
  accepts 44 000 notifications per second and drains 3 500 per second on a
  laptop ([method](docs/BENCHMARKS.md)). 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, 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.

<p align="center">
  <a href="https://github.com/rmzlb/notifyd/releases/download/v0.2.1/notifyd-explainer.mp4"><img src="docs/assets/notifyd-explainer.gif" alt="60-second explainer: one send call, priority order under a provider 429, an agent operating the instance over MCP" width="880"></a><br>
  <sub>60 s explainer, invented data. <a href="https://github.com/rmzlb/notifyd/releases/download/v0.2.1/notifyd-explainer.mp4">MP4</a> · <a href="docs/video/">Remotion source</a></sub>
</p>

---

## Send in one call

```bash
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](#clients) and [Python](#clients) 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/`](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:

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

| Tool | What the agent can do |
|---|---|
| `digest` | Ranked findings with actions, queue, outcomes, latency, deliverability, per project |
| `list_jobs`, `get_job` | Filter by project, channel, status, recipient, time; see provider, attempts, last error |
| `retry_job`, `cancel_job` | Act on a stuck or wrong send |
| `list_projects`, `update_project` | Sender identity (`from_email`, `from_name`), channels, inbound rate limit, bulk `send_window` in the recipients' timezone |
| `list_suppressions`, `add_suppression`, `release_suppression` | Suppression list with `all` or `marketing` scope |
| `template_metrics` | Sent, failed, bounced, opened per template |
| `send_test` | Prove the pipeline end to end on any channel |

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/`](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`](server.json)). Full operator guide: [docs/AGENT.md](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** — 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