Reference

The complete surface: HTTP endpoints, SDK methods, payload shapes, server options, environment variables, events, and errors.

Authentication

Every route under /v1/ requires a key. Two header forms are accepted:

Authorization: Bearer nk_live_…
x-api-key: nk_live_…

The SSE endpoint also accepts ?token= in the query string, since EventSource cannot set headers.

Status codes

Endpoints

Notifications

Campaigns

A campaign is just a label: pass campaign to POST /v1/notify and every message the call produces is tagged, along with every later engagement event. Sends without one can't be attributed afterwards.

Stats count distinct tasks, not log rows. A task gets a dispatch row, an attempt row and any number of engagement rows, so counting rows would inflate each figure differently. Opening the same email twice counts once.

{
  "campaign": "spring-sale",
  "totals": {
    "sent": 200, "delivered": 194, "failed": 6,
    "opened": 71, "clicked": 12,
    "bounced": 4, "complained": 1, "unsubscribed": 3,
    "deliveryRate": 97.0, "openRate": 36.6, "clickRate": 6.19,
    "bounceRate": 2.0, "complaintRate": 0.52, "unsubscribeRate": 1.55
  },
  "byChannel": { "email": { "sent": 200, "delivered": 194, "opened": 71, "clicked": 12 } },
  "engagementTracked": true,
  "warnings": []
}

Rates are percentages, or null where the denominator is zero. openRate, clickRate, complaintRate, and unsubscribeRate are measured against delivered; deliveryRate and bounceRate against sent.

Unsubscribe

One-click unsubscribe, per RFC 8058. Gmail and Yahoo have required it on bulk mail since early 2024. Without it, bulk sends are throttled or junked, and since reputation attaches to the sending domain, your transactional mail eventually suffers too.

These two routes are the API's only unauthenticated endpoints, since a mail client has no API key. The signed token in the URL is the credential, authorising exactly one opt-out for one address.

Configuration

Headers are attached only when both are set. With either missing, mail still sends, without List-Unsubscribe. A missing UNSUBSCRIBE_SECRET logs at warn whenever it matters: once per bulk email sent without the headers, and once per request to either unsubscribe route, where every token is rejected for lack of a key. Grep for it before assuming your links work.

What gets a header, and what an opt-out does

Headers go only on email whose template has at least one topic. A template with no topic is transactional by convention (a password reset, a receipt) and shouldn't carry an unsubscribe button. Mailbox providers draw the same line: bulk mail must offer one-click; transactional mail is exempt.

The token carries the project, the user's external id, the channel, the address and the topics, signed with HMAC-SHA256 and verified in constant time. Tampered payloads or signatures are rejected, and every failure returns the same response, so the endpoint can't be used to probe which addresses exist.

Suppressions

Destinations never to contact again. Rows are written automatically from provider webhooks on an unsubscribe, spam complaint or hard bounce (soft bounces, a full mailbox or transient outage, don't suppress), and by the unsubscribe endpoint when there's no topic to scope the opt-out to. The engine checks the list before dispatch, overriding everything, including priority: "critical".

reason is one of unsubscribed, complained, bounced or manual. Targets are normalised for storage and lookup (email lower-cased, everything else trimmed), so a suppression for [email protected] still blocks [email protected].

Users and contacts

Templates, segments, workflows, events

Projects, system, dead letters

Payload shapes

notify()

interface NotifyRequest {
  // Exactly one of these three is required.
  user?: string | InlineUser | Array<string | InlineUser>;
  segment?: string;
  topic?: string;

  template: string;                       // required
  channels?: Channel[];                   // default ["email"]
  data?: Record<string, unknown>;         // {{placeholder}} values
  aiPrompts?: Record<string, string>;     // merged over the template's own
  priority?: "low" | "normal" | "high" | "critical";               // default "normal"
  fallback?: boolean;                     // channels become an ordered chain
  sendAt?: string;                        // ISO 8601, UTC
  campaign?: string;                      // groups this send for /v1/campaigns reporting
}

type Channel =
  | "email" | "sms" | "push" | "webhook"
  | "slack" | "whatsapp" | "telegram" | "discord"
  | "in-app";

interface InlineUser {
  id: string;
  language?: string;
  timezone?: string;
  email?: string | string[];
  phone?: string | string[];
  pushToken?: string | string[];
  segments?: string[];
  preferences?: Preferences;
}

Preferences

interface Preferences {
  channels?: Record<string, boolean>;     // false disables that channel entirely
  topics?: Record<string, boolean>;       // false opts out of templates carrying that topic
  quietHours?: { start: string; end: string }[];   // "HH:MM", 24h, user's timezone
}

Template

interface Template {
  id: string;
  channel: Channel;
  topic?: string | string[];              // drives topic opt-outs
  content: Record<string, unknown>;       // free-form; strings are interpolated
  aiPrompts?: Record<string, string>;     // key becomes a template variable
}

content is free-form, but transports read known keys: subject, text (or body) and html (or htmlBody) on every first-party transport, plus from and replyTo on email, which override the transport's sender for that template. See Templates & AI.

triggerWorkflow()

interface TriggerWorkflowRequest {
  name: string;                           // required — the registered workflow name
  input?: Record<string, unknown>;        // arrives as the handler's `event` argument
  user?: string | InlineUser;             // shorthand for input.user
}

Workflow steps (JSON form)

type WorkflowStep =
  | { action: "notify"; payload: NotifyRequest }
  | { action: "wait"; duration: string }                                    // "30s" "15m" "2h" "3d"
  | { action: "waitForEvent"; event: string; options?: { timeout?: string } };

Durations and timeouts are a number with an s, m, h or d suffix. An unknown unit on a waitForEvent timeout throws rather than reading as zero. Any other action value is logged and skipped.

SDK

import { NotifkitClient } from "notifkit";

const client = new NotifkitClient({
  baseUrl: "https://notifkit.yourdomain.com",
  apiKey: process.env.NOTIFKIT_API_KEY,
  headers: { "x-request-source": "billing-service" },   // optional, merged into every request
  templates: [/* … */],                                 // optional; pushed by client.sync()
});

Non-2xx responses throw an Error with the server's message. There's no built-in retry; add your own policy if needed.

Server options

interface NotifkitOptions {
  // Required. "all" expands to every service.
  services: ("api" | "delivery" | "engine" | "enricher" |
             "scheduler" | "ai" | "workflow" | "events" | "all")[];

  redisUrl?: string;         // required when NODE_ENV=production
  databaseUrl?: string;      // required when NODE_ENV=production
  port?: number;             // default 3000
  logLevel?: "fatal" | "error" | "warn" | "info" | "debug" | "trace" | "silent";
  nodeEnv?: "development" | "test" | "production";

  providers?: Transport[];   // registered at priority 0
  autoMigrate?: boolean;     // default true
  aiModel?: LanguageModel;   // any Vercel AI SDK model
  workerConcurrency?: number;
  deliveryConcurrency?: number;  // default workerConcurrency
  fusedPipeline?: boolean;   // in-memory hand-off when enricher, engine and delivery share a process
  adminUser?: { email: string; password: string; username?: string };  // first dashboard login
  redisOptions?: { maxQueueLength?: number };  // QUEUE_MAX_LEN: backlog cap, see Operations
  dbOptions?: { maxConnections?: number; schema?: string };  // schema: DB_SCHEMA, default "public"
}

start() resolves once every selected service is up; stop() shuts them down gracefully and stops any containers it started.

Environment variables

Precedence: constructor options → environment → .env → defaults. What each one does is in Operations.

Events

NotifkitServer extends Node's EventEmitter.

reason on a skip is one of user_opted_out, channel_disabled, template_not_found, or no_active_contacts.

Transport interface

interface Transport {
  readonly channel: NotificationChannel;
  readonly limits?: { limit: number; windowSeconds: number };

  send(task: NotificationDispatchedPayload): Promise<DeliveryResult>;

  webhookPath?: string;
  verifyWebhook?(rawBody: string, headers: Record<string, string | string[] | undefined>)
    : Promise<boolean> | boolean;
  parseWebhook?(body: any, rawBody?: string, headers?: Record<string, string | string[] | undefined>)
    : Promise<WebhookEvent[]>;
}

interface DeliveryResult {
  success: boolean;
  providerMessageId?: string;
  invalidToken?: boolean;    // push only — deactivates the contact
  error?: string;
}

interface WebhookEvent {
  providerMessageId: string;
  status: "opened" | "clicked" | "bounced" | "complained" | "unsubscribed";
  timestamp?: Date;

  // Required to suppress. The delivery log records the message, not the
  // destination, so without this an unsubscribe or bounce can be logged
  // but not acted on — the address keeps receiving mail.
  recipient?: string;

  // Only "hard" suppresses. Undefined is read as "soft", so a provider that
  // does not distinguish them never suppresses a working address.
  bounceType?: "hard" | "soft";

  // Kept on the log row: the clicked URL, the bounce description.
  metadata?: Record<string, unknown>;
}

import { registerTransport } from "notifkit";
registerTransport(transport, /* priority */ 10);   // higher priority is tried first

Workflow API

import { workflow } from "notifkit";

workflow("name", async ({ step, event }) => { /* … */ });

interface WorkflowStepContext {
  // Every field notify() takes. Name no target and it goes to the
  // instance's own user; name one and it wins.
  notify(payload: WorkflowNotifyInput): Promise<{
    success: boolean;
    messageId: string;
    notificationId: string;
  }>;
  wait(duration: string): Promise<void>;
  waitForEvent(
    eventName: string,
    options?: { timeout?: string; match?: Record<string, any> },   // "30s" "15m" "2h" "3d"
  ): Promise<any | null>;
  run<T>(name: string, fn: () => Promise<T> | T): Promise<T>;
}

A waitForEvent that times out resolves to null, and to null again on every replay: the timeout is recorded as the step's outcome, so a branch on === null stays stable across restarts. An event arriving just after the timer doesn't undo the timeout.

Errors

Constants