API reference

createNotifyKit()

Builds the instance everything else hangs off. Only notifications and database are required. The configuration is validated on the spot: any error throws a NotifyKitError with code INVALID_CONFIG listing every problem at once, and warnings are logged.

import { createNotifyKit, setTimeoutQueue } from "@notifykitjs/core"
import { drizzlePostgresAdapter } from "@notifykitjs/drizzle"
import { resendProvider } from "@notifykitjs/resend"

export const notify = createNotifyKit({
	notifications: [commentMentioned, orderShipped] as const,
	database: drizzlePostgresAdapter(db),
	providers: { email: resendProvider({ apiKey, from }) },
	queue: setTimeoutQueue(),
	retry: { maxAttempts: 5 },
	unsubscribe: {
		secret: process.env.NOTIFYKIT_SECRET!,
		baseUrl: "https://app.com/api/notifykit",
	},
})

send()

const result = await notify.send({
	recipientId: "user_123",
	notificationId: "comment_mentioned",   // one of your ids
	payload: { actorName: "Rey", postTitle: "Launch Plan", postUrl: "/posts/42" },
	tenantId: "org_1",                     // or organizationId; optional
	workspaceId: "ws_1",                   // optional
	idempotencyKey: "comment_981",         // optional, up to 256 characters
	dedupeKey: "post_42", dedupeWindowMs: 60_000, // optional, together
})

notificationId narrows the type of payload, so a wrong field is a compile error. send() is for trusted server code: it uses recipientId as given, with no check of who is asking. Browser code goes through the handler routes, which get the user from your identify().

It resolves to a SendResult:

Pass dryRun: true and send() returns a DeliveryExplanation instead, the same as explain().

When send() throws

A provider that fails does not make send() reject. The delivery is retried, then marked failed, the delivery.failed hook fires, and any fallback runs. send() throws for mistakes in the call itself:

PayloadValidationError extends NotifyKitError. Every NotifyKitError carries code, and where relevant notificationId, channel, recipientId, field, and a fix suggestion.

explain() and check()

const plan = await notify.explain({ recipientId, notificationId, payload })
plan.channels.map((c) => `${c.channel}: ${c.outcome} (${c.reason})`)
// ["inbox: deliver (...)", "email: disabled (...)"]

Takes the same input as send() and says what would happen, without writing or sending anything. check() is the same method under another name. The result, a DeliveryExplanation, has an outcome per channel plus the idempotency, dedupe, rate-limit, digest, and quiet-hours state. See Explain and dry run and the type.

Recipients

await notify.upsertRecipient({
	id: user.id,
	email: user.email,         // needed for email
	phone: user.phone,         // needed for SMS
	name: user.name,
	tenantId: user.orgId,      // optional scope
	quietHours: { start: "22:00", end: "08:00", timezone: "America/Toronto" },
})

A recipient’s tenant and workspace are fixed once set: upserting the same id with a different one throws TENANT_REASSIGNMENT or WORKSPACE_REASSIGNMENT. Calling it on every sign-in is safe.

notify.inbox

Server-side access to inbox items. Every method takes the recipient explicitly, plus an optional scope ({ tenantId?, organizationId?, workspaceId? }). Methods that act on one item check it belongs to that recipient and scope.

Each change publishes a realtime event if a realtime adapter is set, and fires the matching inbox.* hook.

notify.preferences

Preferences are channel maps such as { email: false }, stored at three levels: per notification, per category, and global. Every input also accepts tenantId, organizationId, and workspaceId. See Preferences for how the levels combine.

notify.deliveries

deliveries.list(recipientId?, scope?, limit?) returns DeliveryRecord[], including the rendered subject and body. Leave out recipientId to list everyone’s. It is for trusted code only; the handler’s GET /deliveries route checks permissions and removes the message content.

Timeline and Redaction

Lifecycle

Digest windows and quiet-hours deferrals run on timers inside the process. These methods let you wait for, force, or recover that work. All resolve to nothing.

Properties

Other Exports

Everything else @notifykitjs/core exports, by job:

• Defining: notification(), channel.inbox(), .email(), .sms(), .webhook(). Schema helpers zodPayload(), valibotPayload(), and arktypePayload() come from @notifykitjs/core/zod, /valibot, and /arktype. See Defining.
• HTTP: createHandler(notify, options). See Handler routes.
• Storage and transport: memoryAdapter(), memoryRealtimeAdapter(), inlineQueue(), setTimeoutQueue({ onError? }), defaultRetryPolicy.
• Providers: webhookProvider({ secret?, timeoutMs?, fetch? }), verifyWebhookSignature(body, signatureHeader, secret), and the fakes fakeEmailProvider(), fakeSmsProvider(), fakeWebhookProvider(). See Providers.
• Unsubscribe: signUnsubscribeToken(claims, secret) and verifyUnsubscribeToken(token, secret), where secret can be an array to accept old secrets while you rotate.
• Validation: validateConfig(input) returns the startup checks as ValidationIssue[] without throwing, and formatValidationIssues(issues) prints them. Also on @notifykitjs/core/validate.
• Utilities: renderTemplate(), extractTemplateVars(), redactPayload(payload, fields), createId(prefix), the error classes NotifyKitError and PayloadValidationError, and the lists SKIP_REASONS and TIMELINE_EVENT_TYPES.
• Preference keys: GLOBAL_PREFERENCE_KEY, categoryPreferenceKey(category), isCategoryPreferenceKey(), isSyntheticPreferenceKey(), and parseCategoryFromKey(), for code that reads preference rows directly.