Quickstart

Seven steps, nothing assumed. You end with a running notifkit server, a project, a template, a user, and a notification landing in your terminal. About ten minutes, or one if you scaffold it.

The one-command version

create-notifkit writes the walkthrough below into a new directory: a server, a script that creates the project, and a script that sends. It also puts a random ADMIN_API_KEY in .env. Needs Node 22+ and Docker running.

npm create notifkit@latest my-app     # or: npx notifkit create my-app
cd my-app
npm run dev                           # starts the server; leave it running

In a second terminal:

npm run setup     # creates a project and writes NOTIFKIT_API_KEY to .env
npm run send      # syncs a template, adds a user, sends to them

The notification prints in the server terminal, since the default provider is the console transport. For a real one, pass --provider and fill in the credentials it lists in .env:

Other flags: --no-install skips installing dependencies; --force writes into a non-empty directory. Pass . as the name to use the current directory. pnpm, yarn and bun work too: pnpm create notifkit my-app.

Two processes, not one

Most early mix-ups come from missing this: notifkit is a server you run, and your application talks to it over HTTP. They are separate processes, can live on separate machines, and your application needn't be JavaScript.

Each step below is tagged with where it runs: server is the notifkit process, your app is your code, and one-off is a bootstrap task you do once by hand.

The path you are about to walk

Left to right: the first two boxes you do once; the rest is your application, and only notify runs on every event:

Before you start

1. Install and lay out the files Setup One package for the engine, one for a transport that prints to your terminal.

   mkdir notifkit-demo && cd notifkit-demo
   npm init -y
   npm pkg set type=module
   npm install notifkit @notifkit/provider-console
   
   # tsx runs the TypeScript directly. The testcontainers packages are what let
   # the server start its own Postgres and Redis — notifkit keeps them external,
   # so they do not arrive with it. Skip them if you already run both and will
   # pass their URLs instead.
   npm install -D tsx @testcontainers/postgresql @testcontainers/redis
   
   # The three files this guide builds:
   touch server.ts notifkit.ts app.ts

   All three files share a directory to keep the walkthrough short, but they are two separate programs:

   notifkit-demo/
   ├── server.ts     ← the notifkit server        · step 2 · runs on its own, stays up
   │                   NotifkitServer + providers
   │
   ├── notifkit.ts   ← the client                 · step 4 · your app's handle on the server
   │                   NotifkitClient({ baseUrl, apiKey })
   │
   └── app.ts        ← your application           · steps 5–7 · imports notifkit.ts
                       syncTemplates / addUser / notify

   Run them as two processes: npx tsx server.ts in one terminal, npx tsx app.ts in another. In production they're two deployments, often two repositories. If app.ts isn't JavaScript, notifkit.ts disappears and you make the HTTP calls directly.

2. Start the server server One process runs all eight services. It also creates its own database schema.

   NotifkitServer is the whole engine. services: ["all"] runs the API and every worker in one process: right for development, and one config change from separate deployments later.

   import { NotifkitServer } from "notifkit";
   import { ConsoleTransport } from "@notifkit/provider-console";
   
   // Enables POST /v1/projects. Without it, project creation returns 403.
   process.env.ADMIN_API_KEY = "dev-admin-key";
   
   const server = new NotifkitServer({
     services: ["all"],
     nodeEnv: "development",
     port: 3000,
   
     // Omit redisUrl and databaseUrl and notifkit starts throwaway Postgres +
     // Redis containers for you. That path is gated on nodeEnv: any value but
     // "production" gets containers, and "production" requires both URLs and
     // fails startup without them.
   
     // ConsoleTransport defaults to the "push" channel — we want email.
     providers: [new ConsoleTransport({ channel: "email" })],
   });
   
   await server.start();
   console.log("notifkit listening on http://localhost:3000");

   npx tsx server.ts

   Startup is chatty on purpose. Look for these lines:

   INFO (server): No databaseUrl provided, spinning up PostgreSQL container...
   INFO (server): Running database migrations...
   INFO (server): Database migrations complete
   INFO (server): Registered 1 custom providers
   INFO (delivery): delivery starting {"channels":["email"]}
   INFO (api): api server listening {"port":3000,"host":"127.0.0.1"}

   Confirm from a second terminal:

   curl -s http://localhost:3000/health | jq

   {
     "service": "api",
     "status": "ok",
     "redis": true,
     "database": true,
     "workers": {
       "enricher": { "state": "running", "processedCount": 0 },
       "engine":   { "state": "running", "processedCount": 0 },
       "delivery": { "state": "running", "processedCount": 0 }
     }
   }

   Heads up

   Only the probe routes (/health, /live, /ready, /metrics) work without a key. Everything under /v1/ needs one, which the next step gets you.

3. Create a project and grab the API key one-off A project is the tenant boundary: every user, template and log row belongs to one.

   Project creation is the bootstrap, so it's the one endpoint that takes the admin key instead of a project key. The response holds the only copy of the new API key: it's stored as a SHA-256 hash and can't be read back.

   ADMIN_API_KEY=dev-admin-key npx notifkit-create-project "demo"

   Project "demo" created. Save the API key now — it is not recoverable.
   
   NOTIFKIT_PROJECT_ID=6f1c9c1e-6d5e-4d0c-9a2b-3f77e5b8a1d4
   NOTIFKIT_API_KEY=nk_live_9f3c…

   Keep it in your shell for the rest of the walkthrough:

   export NK_KEY="nk_live_9f3c…"

   Shortcut

   Or skip the curl: with the MCP server configured, ask your agent to set up the project and hand you the keys. The dashboard can create them too.

   Gotcha

   Lost the key? It can't be recovered; mint a new one with POST /v1/projects/{id}/keys. Keys are admin or read_only. A read-only key gets 403 on any non-GET request, so use it for dashboards.

4. Point your application at the server your app From here on it's your code calling the server. Set it up once.

   The remaining steps have two tabs. HTTP is a plain request from any language, and what the SDK sends under the hood. TypeScript uses NotifkitClient, a typed wrapper over the same endpoints.

   On the HTTP tab, the $NK_KEY you exported in the previous step is all you need. Skip ahead.

   On the TypeScript tab, this is the notifkit object every later snippet calls. It belongs in your application, in a different file and usually a different process from server.ts:

   import { NotifkitClient } from "notifkit";
   
   // Note: NotifkitClient, not NotifkitServer. This is a client for the
   // API you started in step 2 — it holds no database or Redis connection.
   export const notifkit = new NotifkitClient({
     baseUrl: "http://localhost:3000",
     apiKey: process.env.NOTIFKIT_API_KEY,   // the nk_live_… key from step 3
   });

   Gotcha

   Don't send notifications with the server object from step 2. NotifkitServer is the infrastructure; NotifkitClient is how you talk to it. Different classes, different jobs, and in production usually different deployments.

5. Sync a template your app Content lives in notifkit, not your service code; sends reference it by id.

   A template is an id, a channel and a content object. notifkit doesn't care which keys content has: it substitutes {{placeholders}} in every string. The transport decides which keys it reads; Resend, FCM and console all look for subject, text (or body) and html (or htmlBody).

   curl -s -X PUT http://localhost:3000/v1/templates \
     -H "Authorization: Bearer $NK_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "templates": [{
         "id": "welcome",
         "channel": "email",
         "topic": ["transactional"],
         "content": {
           "subject": "Welcome aboard, {{name}}",
           "text": "Hi {{name}}, thanks for joining {{company}}.",
           "html": "<h1>Hi {{name}}</h1><p>Thanks for joining {{company}}.</p>"
         }
       }]
     }'

   await notifkit.syncTemplates({
     templates: [{
       id: "welcome",
       channel: "email",
       topic: ["transactional"],
       content: {
         subject: "Welcome aboard, {{name}}",
         text: "Hi {{name}}, thanks for joining {{company}}.",
         html: "<h1>Hi {{name}}</h1><p>Thanks for joining {{company}}.</p>",
       },
     }],
   });

   { "synced": 1 }

   PUT upserts the whole list, so it's safe on every deploy. That's how templates are meant to live in version control with your app.

   Note

   Per-topic opt-outs key on the topic array. A user with topics.transactional = false never receives this template on any channel. Templates with no topic can't be opted out of, which is what you want for password resets.

6. Register a user your app A user is an id, addresses, and rules for when to contact them. Wire it into your signup handler.

   Use your own database's user id. Addresses passed as email, phone or pushToken become contacts, the endpoints notifkit delivers to. Each takes a string or an array.

   curl -s -X POST http://localhost:3000/v1/users \
     -H "Authorization: Bearer $NK_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "id": "usr_123",
       "contacts": [{ "channel": "email", "target": "[email protected]" }],
       "timezone": "America/New_York",
       "preferences": {
         "channels": { "email": true, "sms": false },
         "topics":   { "transactional": true, "marketing": false },
         "quietHours": [{ "start": "22:00", "end": "08:00" }]
       }
     }'

   await notifkit.addUser("usr_123", [
     { channel: "email", target: "[email protected]" }
   ], {
     timezone: "America/New_York",
     preferences: {
       channels: { email: true, sms: false },
       topics:   { transactional: true, marketing: false },
       quietHours: [{ start: "22:00", end: "08:00" }],
     },
   });

   { "id": "usr_123" }

   It's an upsert: calling it again with the same id updates the record. Calling it from your signup and profile-update handlers is usually all the integration users need.

   Note

   quietHours are HH:MM windows in the user's own timezone, and may wrap midnight. With no timezone set, UTC is used.

7. Send it your app The call you'll make over and over, wherever the event happens.

   curl -s -X POST http://localhost:3000/v1/notify \
     -H "Authorization: Bearer $NK_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "user": "usr_123",
       "template": "welcome",
       "channels": ["email"],
       "data": { "name": "Alice", "company": "Acme" }
     }'

   await notifkit.notify({
     user: "usr_123",
     template: "welcome",
     channels: ["email"],
     data: { name: "Alice", company: "Acme" },
   });

   You get 202 Accepted immediately. It's an enqueue, not a delivery receipt:

   {
     "messageId": "1737054981234-0",
     "notificationId": "0f8c2b7e-1a4d-4c93-9f2e-7d1b6a5c8e30",
     "target": { "type": "user", "userId": "usr_123" }
   }

   Within a second or so, the server terminal shows:

   INFO (EnricherWorker): event enriched          {"target":"user"}
   INFO (EngineWorker):   task dispatched         {"taskId":"…","recipientId":"usr_123"}
   
   ┌─────────────────  📲  PUSH NOTIFICATION  ─────────────────
   │ to token : [email protected]
   │ recipient: usr_123
   │ priority : normal
   │ content  : {"subject":"Welcome aboard, Alice","text":"Hi Alice, thanks
   │             for joining Acme.","html":"<h1>Hi Alice</h1>…"}
   │ taskId   : 0f8c2b7e-…
   └───────────────────────────────────────────────────────────
   
   INFO (DeliveryWorker): notification delivered  {"channel":"email"}

   That's the whole loop: placeholders filled, preferences checked, rendered payload handed to a transport.

   Note

   The console transport prints a push-shaped banner whatever the channel. It's a debugging aid, not a faithful renderer; the content line is what matters.

Confirm it, from the outside

Terminal output suits a demo; delivery history is what you'll actually use. Every attempt is written to Postgres and readable per project:

curl -s "http://localhost:3000/v1/notifications/logs?limit=5" \
  -H "Authorization: Bearer $NK_KEY" | jq

const { logs, nextCursor } = await notifkit.getNotificationLogs({ limit: 5 });

{
  "logs": [
    {
      "taskId": "0f8c2b7e-…",
      "templateId": "welcome",
      "channel": "email",
      "status": "delivered",
      "attempt": 1,
      "providerMessageId": "console-1737054981567",
      "timestamp": "2026-01-16T18:36:21.567Z"
    }
  ],
  "nextCursor": null
}

Filter by templateId, channel, status or workflowInstanceId; page with cursor.

Reacting to deliveries instead of polling server

Two ways to hear about deliveries as they happen, depending on where your code sits. From outside the server, in any language, subscribe to the SSE stream. From inside server.ts, NotifkitServer is an EventEmitter, so attach listeners to the server object from step 2. The in-process route gets one extra event the stream doesn't carry:

# From outside the server process, subscribe to the SSE stream.
# It carries delivery:delivered and delivery:failed — not notification:skipped.
curl -N "http://localhost:3000/v1/events/stream?token=$NK_KEY"

# event: delivery:delivered
# data: {"taskId":"0f8c…","providerMessageId":"console-173…","channel":"email"}

server.on("delivery:delivered", (taskId, providerMessageId, channel) => {
  console.log(`${channel} delivered`, taskId, providerMessageId);
});

server.on("delivery:failed", (taskId, error, channel) => {
  console.error(`${channel} failed`, taskId, error);
});

server.on("notification:skipped", ({ recipientId, reason }) => {
  // reason: "user_opted_out" | "channel_disabled" | "template_not_found" | "no_active_contacts"
  console.warn("skipped", recipientId, reason);
});

Where each call belongs in your app your app

The walkthrough ran the three application calls back to back. In a real service they live in three places, and only the last runs per event:

API=http://localhost:3000
AUTH=(-H "Authorization: Bearer $NK_KEY" -H "Content-Type: application/json")

# ── Deploy-time: push templates from version control.
curl -s -X PUT $API/v1/templates "${AUTH[@]}" \
  -d '{
    "templates": [{
      "id": "welcome",
      "channel": "email",
      "topic": ["transactional"],
      "content": {
        "subject": "Welcome aboard, {{name}}",
        "text": "Hi {{name}}, thanks for joining {{company}}."
      }
    }]
  }'

# ── Signup handler: upsert the user.
curl -s -X POST $API/v1/users "${AUTH[@]}" \
  -d '{
    "id": "usr_123",
    "email": "[email protected]",
    "timezone": "America/New_York",
    "preferences": { "channels": { "email": true } }
  }'

# ── Anywhere something happens: send.
curl -s -X POST $API/v1/notify "${AUTH[@]}" \
  -d '{
    "user": "usr_123",
    "template": "welcome",
    "channels": ["email"],
    "data": { "name": "Alice", "company": "Acme" }
  }'

import { notifkit } from "./notifkit.js";   // the client from step 4

// ── Deploy-time: push templates from version control.
await notifkit.syncTemplates({
  templates: [{
    id: "welcome",
    channel: "email",
    topic: ["transactional"],
    content: {
      subject: "Welcome aboard, {{name}}",
      text: "Hi {{name}}, thanks for joining {{company}}.",
    },
  }],
});

// ── Signup handler: upsert the user.
await notifkit.addUser({
  id: "usr_123",
  email: "[email protected]",
  timezone: "America/New_York",
  preferences: { channels: { email: true } },
});

// ── Anywhere something happens: send.
const { messageId } = await notifkit.notify({
  user: "usr_123",
  template: "welcome",
  channels: ["email"],
  data: { name: "Alice", company: "Acme" },
});

When nothing arrives

The pipeline drops instead of throwing, so a silent send is the normal failure mode. The server always logs the reason at info level: start there.

Next