notifkit

You shouldn't have to build a notification system.

Self-hosted notification infrastructure for product notifications. One API call handles email, SMS, push, and webhooks — with preferences, quiet hours, retries, fallback, scheduling, workflows, and delivery logs built in.

Documentation · Quickstart · Examples · notifkit.dev

The first notification is easy

await sendEmail({
  to: user.email,
  subject: "Order Shipped",
  ...
});

Then reality hits

Users opt out. People are asleep. Push tokens die. Providers throw 503s. Some channels fail and need fallback. You need timezone-aware quiet hours, future scheduling, deduplication, multi-channel templates, delivery logs, unsubscribe handling, multi-step workflows, and a dead-letter queue nobody wants to maintain.

notifkit is that machinery, already built.

Your app makes one typed call. notifkit handles the rest — who gets it, which channel to use, when to send it, whether they're allowed to receive it, and what happens when delivery fails.

import { notifkit } from "notifkit";

await notifkit.notify({
  user: "usr_123",
  template: "order-shipped",
  channels: ["push", "email"],
  fallback: true,
});

Push first. If it fails, email.

Preferences, consent, quiet hours, retries, deduplication, throttling, template rendering, and delivery tracking happen behind that single call.

What actually runs

notifkit is both an orchestration engine and a typed SDK.

flowchart TD
    App["Your Application / AI Agent<br/>Typed SDK · REST API · MCP Server"]

    App -->|"HTTP POST /v1/notify"| API

    API["Notifkit API Server<br/>Schema Validation · Auth · Multi-Tenancy<br/>Idempotency Gate · Priority Queue Ingestion"]

    API --> PG
    API --> REDIS

    PG[("PostgreSQL — Storage<br/>Users · Preferences<br/>Templates · Workflows<br/>Delivery Logs · DLQ")]
    REDIS[("Redis — Streams / ZSET<br/>Priority Queues<br/>Scheduled Sends<br/>Sliding Rate Limits")]

    subgraph WORKERS["Background Workers Pipeline"]
        direction LR
        ENRICH["Enricher<br/>(Resolve)"] --> ENGINE["Engine<br/>(Quiet Hours)"] --> DELIVER["Delivery<br/>(Rate Limits / CB)"]
        ENGINE --> SCHED["Scheduler<br/>(sendAt / QH)"]
        SCHED --> DELIVER
    end

    REDIS -->|"consume"| ENRICH
    ENRICH -.->|"read / write state"| PG
    DELIVER -.->|"delivery logs"| PG
    DELIVER -->|"Dispatch"| PROVIDERS

    PROVIDERS["Provider Transports<br/>Email: Resend, SES, Postmark · Push: Firebase (FCM)<br/>SMS: Twilio, MessageBird · Webhooks: Custom HTTP"]

    classDef entry stroke:#6366f1,stroke-width:2px
    classDef store stroke:#0ea5e9,stroke-width:2px
    classDef work stroke:#22c55e,stroke-width:2px
    class App,API,PROVIDERS entry
    class PG,REDIS store
    class ENRICH,ENGINE,DELIVER,SCHED work

• NotifkitServer: Runs the HTTP REST API router (/v1/notify, /health, /metrics) and the background worker pipelines (enricher, decision engine, scheduler, delivery).
• NotifkitClient: The lightweight client your application uses to trigger notifications, sync templates, and manage users over HTTP.

Topologies

• Single Process (Monolith): Run the API and all workers in the same Node.js process (services: ["all"]). Perfect for small-to-medium apps, side projects, and staging.
• Distributed Services: Run stateless API servers (services: ["api"]) behind a load balancer and scale worker pools (services: ["enricher", "engine", "delivery", "scheduler"]) horizontally across Redis Streams consumer groups.

Battle-tested for production

Battle-tested in production: notifkit powers production notification pipelines handling thousands of emails, push notifications, and OTPs every day.

It is the infrastructure we built because we needed it ourselves — rather than spending months reinventing distributed notification plumbing or paying SaaS tolls per alert.

Your servers. Your providers. Your data. Zero notification SaaS markups.

Reliability & Chaos Engineering

Because notification delivery is mission-critical, every pipeline component is tested against extreme failure conditions:

flowchart LR
    S1["Redis Streams"] -->|"Kill Worker (SIGKILL)"| M1["Auto-Claim and Replay"] --> O1["Zero Lost Messages"]
    S2["Connection Loss"] -->|"Drop DB / Redis"| M2["Auto-Reconnect / Retry"] --> O2["In-Flight State Intact"]
    S3["10k+ Messages"] -->|"Burst"| M3["Concurrency and Limits"] --> O3["Flat Memory, No Leaks"]

    classDef fault stroke:#ef4444,stroke-width:2px
    classDef guard stroke:#6366f1,stroke-width:2px
    classDef result stroke:#22c55e,stroke-width:2px
    class S1,S2,S3 fault
    class M1,M2,M3 guard
    class O1,O2,O3 result

• Chaos Monkey Testing (tests/chaos/crash.test.ts): Background worker processes are randomly terminated with SIGKILL during active, high-throughput message streaming. Consumer group Pending Entries List (PEL) re-claims guarantee zero lost messages and seamless failover.
• Infrastructure Recovery Testing (tests/chaos/recovery.test.ts): PostgreSQL and Redis connections are forcefully severed and restored under live traffic. Verifies automatic client reconnection, worker backpressure, and durable state resumption.
• High-Throughput Load Testing (tests/chaos/load.test.ts): Stressed with bursts of 10,000+ notifications across parallel worker pools, verifying queue drain velocity, sliding-window rate limiters, and flat memory profiles without leaks.
• Race Conditions & Concurrency (tests/race-conditions.test.ts, tests/idempotency.test.ts): Hardened against concurrent duplicate dispatches, overlapping quiet-hour boundary evaluations, atomic user updates, and 24-hour idempotency key deduplication.
• 100% Real Ephemeral Containers: Unit, integration, and chaos test suites execute against real PostgreSQL and Redis containers via Testcontainers, eliminating mocks for core storage and streaming primitives.

What you get

The idea is simple: You decide what to say. notifkit handles getting it there reliably.

What notifkit is — and what it isn't

What it is: the durable notification infrastructure layer running directly inside your own stack.

What it isn't: a marketing automation suite.

notifkit is not Customer.io, OneSignal, or SendGrid. You bring your own provider accounts — your keys, your billing, your deliverability.

First-party providers ship for Resend and Firebase Cloud Messaging. Anything else is a simple Transport class with a send() method.

Quickstart

1. Install

npm install notifkit @notifkit/provider-resend

2. Run the engine and dispatch your first notification

import { NotifkitServer, NotifkitClient } from "notifkit";
import { ResendTransport } from "@notifkit/provider-resend";

// 1. Start the server (runs API + workers; auto-starts Postgres & Redis in dev)
const server = new NotifkitServer({
  services: ["all"],
  port: 3000,
  providers: [new ResendTransport({ apiKey: process.env.RESEND_API_KEY! })],
});
await server.start();

// 2. Instantiate client and register a template
const notifkit = new NotifkitClient({ baseUrl: "http://localhost:3000" });

await notifkit.syncTemplates({