notifkit

notifkit is a self-hosted, MIT-licensed notification infrastructure library built by devkitshq. It collapses the entire notification delivery stack — multi-channel routing, preferences, quiet hours, retries, fallback, scheduling, durable workflows, and delivery logs — into a single typed notify() call. The project is written in TypeScript, runs on Node.js 22+, and stores state in PostgreSQL and Redis.

What It Is

notifkit is an orchestration engine and typed SDK for product notifications. Rather than replacing a SaaS like Customer.io or SendGrid, it is the durable delivery layer that runs inside your own infrastructure using your own provider accounts. You bring credentials for Resend, Firebase Cloud Messaging, Twilio, Slack, Telegram, Discord, or WhatsApp; notifkit handles everything between your application code and the provider API. The core platform source code is publicly available on GitHub under the MIT License, making it genuinely open source.

Architecture and Deployment Model

notifkit runs as an HTTP REST API server alongside a set of background worker pipelines — enricher, decision engine, scheduler, and delivery — all backed by Redis Streams and PostgreSQL:

• Single-process mode (services: ["all"]): API and all workers in one Node.js process, suitable for small apps and staging.
• Distributed mode: stateless API servers behind a load balancer with horizontally scaled worker pools consuming from Redis Streams consumer groups.
• Development: Docker is the only prerequisite; notifkit auto-starts throwaway PostgreSQL and Redis containers via Testcontainers.
• Production: Node 22+, a real PostgreSQL instance, and a Redis instance; migrations run via drizzle-kit.

The delivery pipeline processes every notify() call through deduplication, preference checks, quiet-hours evaluation, template rendering, suppression list checks, delivery, and retry/fallback — in that order.

Reliability and Failure Handling

The project ships with a dedicated chaos test suite covering crash recovery, infrastructure reconnection, and load scenarios:

• Crash testing: workers killed with SIGKILL mid-send; Redis Streams consumer group PEL re-claims ensure zero lost messages.
• Infrastructure recovery: PostgreSQL and Redis connections severed and restored under live traffic.
• Load testing: bursts of 10,000+ notifications across parallel worker pools, checking queue drain speed and memory stability.
• Idempotency: 24-hour deduplication via idempotency keys prevents duplicate sends on retries or replays.
• Fallback chains: ordered multi-channel fallback (e.g., push → email → SMS) with circuit breakers per provider.

Agent-Operable via MCP

notifkit ships an MCP server (@notifkit/mcp) that exposes the full REST API surface to AI agents. Compatible with Claude Code, Cursor, Claude Desktop, Gemini, and any MCP-compatible agent, it allows agents to send notifications, run campaigns, inspect delivery logs, manage templates, trigger workflows, and replay dead-letter messages — all through the same API key the application uses. The homepage demonstrates a Claude session queuing a 200-recipient campaign, checking stats, and diagnosing suppressed deliveries without opening a browser dashboard.

Channel and Provider Coverage

A single notify() call can fan out across eight channels simultaneously:

• Email: Resend (@notifkit/provider-resend)
• Push: Firebase Cloud Messaging (@notifkit/provider-fcm)
• SMS: Twilio (@notifkit/provider-twilio)
• Chat: Slack, Telegram, Discord, WhatsApp (Meta Cloud API)
• Webhooks: any HTTP endpoint

Any provider not covered by a first-party package can be added by implementing a Transport class with a single send() method.

Durable Workflows

Beyond one-off notifications, notifkit supports multi-step stateful workflows using step.wait(), step.waitForEvent(), and step.notify(). A workflow can suspend for days, resume after a matching event arrives, and survive multiple deploys in between — the homepage example shows a cart-recovery workflow that waits 45 minutes, listens for an order.placed event for 24 hours, and only sends a discount nudge if the cart is still abandoned. Workflows are defined in code, reviewed in pull requests, and rolled back with git revert.

Current Status

The repository was created in July 2026 and last pushed in September 2026, with 113 stars and 0 open issues as of the latest metadata. The project's author states it runs in production at their own company, according to the README, delivering over 100,000 notifications per day across email, push, and OTPs.