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 with it, as is every engagement event that comes back later. Sends made without one are not attributable after the fact.

Stats count distinct tasks, not log rows — one task accrues 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 because reputation attaches to the sending domain, that eventually drags your transactional mail down too.

These two routes are the only unauthenticated endpoints in the API. They are reached from a mail client, which has no API key — the signed token in the URL is the credential, and it authorises exactly one opt-out for one address.

Configuration

Headers are attached only when both of these are set. With either missing, mail still sends — it just carries no List-Unsubscribe. A missing UNSUBSCRIBE_SECRET is logged at warn each time it would have mattered: once per bulk email sent without the headers, and once per request to either unsubscribe route, where every token is rejected because there is no key to verify it against. Grep for it before assuming your links are live.

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

Headers are attached only to email whose template has at least one topic. A template with no topic is transactional by this codebase's convention — a password reset, a receipt — and those should not carry an unsubscribe button at all. That is also exactly the line mailbox providers draw: 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. A tampered payload or signature is rejected, and every failure returns the same response, so the endpoint cannot be used to probe which addresses exist.

Suppressions

Destinations that must not be contacted again. Rows are written automatically from provider webhooks on an unsubscribe, a spam complaint, or a hard bounce — soft bounces are a full mailbox or a transient outage and do not suppress — and by the unsubscribe endpoint when there is no topic to scope the opt-out to. The engine checks this list before dispatch, and it overrides everything else including priority: "critical".

reason is one of unsubscribed, complained, bounced, or manual. Targets are normalised before storage and lookup — email addresses are lower-cased, everything else is trimmed — so a suppression recorded as Bob@Example.com still blocks a send to bob@example.com.

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?: ("email" | "sms" | "push" | "webhook" | "in-app")[];  // 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
}

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: "email" | "sms" | "push" | "webhook" | "in-app";
  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 from it: subject, text (or body), and html (or htmlBody) on every first-party transport, plus from and replyTo on email, which override the transport's own 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 unrecognised unit on a waitForEvent timeout throws rather than being read 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 are thrown as an Error carrying the server's message. There is no built-in retry — wrap calls in your own policy if you need one.

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;
  redisOptions?: { maxQueueLength?: number };
  dbOptions?: { maxConnections?: number };
}

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.

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 keeps resolving to null on every later replay of the instance — the timeout is recorded as the step's outcome, so a branch on === null stays stable across restarts. The event arriving a moment after the timer fired does not un-time-out the step.

Errors

Constants