# notifkit

> Self-hosted notification infrastructure that handles email, SMS, push, and webhooks with a single notify() call, including preferences, quiet hours, retries, fallback, scheduling, and workflows.

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.

## Features
- Single notify() call for multi-channel delivery
- Email, SMS, push, Slack, WhatsApp, Telegram, Discord, and webhook channels
- Ordered multi-channel fallback with circuit breakers
- Timezone-aware quiet hours with deferral
- 24-hour idempotency key deduplication
- Durable multi-step workflows with wait and waitForEvent
- Redis Streams consumer groups for crash-safe delivery
- Dead-letter queue with replay
- Priority queues (low, normal, high, critical)
- Future scheduling with sendAt and cancellation
- Per-user channel and topic preferences
- RFC 8058 one-click unsubscribe and hard-bounce suppression
- Campaign targeting by user, list, segment, or topic
- Template interpolation with destination-aware escaping
- Optional LLM augmentation via Vercel AI SDK
- MCP server for AI agent operation
- Prometheus metrics, health, and readiness endpoints
- Queryable delivery logs and campaign reporting
- Multi-tenancy with isolated project keys and rate limits
- Local read-only dashboard included
- REST API accessible from any language
- TypeScript typed SDK

## Integrations
Resend, Firebase Cloud Messaging (FCM), Twilio, Slack, WhatsApp (Meta Cloud API), Telegram, Discord, PostgreSQL, Redis, Claude, ChatGPT, Gemini, Cursor, Vercel AI SDK, Testcontainers, Prometheus, Docker

## Platforms
WEB, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Links
- Website: https://notifkit.dev
- Documentation: https://notifkit.dev/docs/index.html
- Repository: https://github.com/devkitshq/notifkit
- EveryDev.ai: https://www.everydev.ai/tools/notifkit