Notifications
Send a notification, then follow it through the delivery log. One call can reach one user or a whole segment, now or later.
One notify() call fans out into tasks: one per user, channel and address (push is one per user). Status, cancellation and the log all work on task IDs, which you read from the delivery log or the scheduled list. notify() doesn't return them.
Send a notification
POST/v1/notify
Auth: Project key with the admin role, or the admin key or a writable session with x-project-id.
Queues a notification and answers right away. Exactly one of user, segment or topic is required. Every message then passes the opt-out, quiet-hours, throttle and suppression checks on its own, and a message dropped by a check doesn't change this response.
Headers
| Header | Type | Description |
|---|---|---|
x-idempotency-key | string | Drops repeats of this key for 24 hours. With several users, each gets <key>-<index>. |
Body
| Field | Type | Required | Description |
|---|---|---|---|
user | string, object or array | one of three | A user id, an inline user (same fields as POST /v1/users, saved before sending), or an array of either. |
segment | string | one of three | Every user tagged with this segment. |
topic | string | one of three | Every user whose preferences.topics[topic] is true. |
template | string | yes | Template id. |
data | object | no | Values for the template's {{placeholders}}. |
channels | string[] | no | Default ["email"]. One of email, sms, push, slack, whatsapp, telegram, discord, webhook, in-app. |
fallback | boolean | no | Default false, which sends on every channel. true tries them in order and stops at the first that delivers. |
priority | string | no | low, normal (default), high or critical. critical skips quiet hours and the throttle. high shares the normal lane. |
sendAt | string | no | UTC date-time, like 2026-11-18T09:00:00Z. Offsets are rejected. It's one instant for everyone, not adjusted to each user's timezone. |
campaign | string | no | Label for campaign stats, up to 128 characters. |
aiPrompts | object | no | Template variable name to prompt. Each is generated per recipient by the configured model. |
Responses
{
"messageId": "1731837600000-0",
"notificationId": "order-99214",
"target": {
"type": "user",
"userId": "usr_123"
}
}
{
"messageId": "1731837600000-1",
"notificationId": "c0d1e2f3-a4b5-4c6d-9e7f-8a9b0c1d2e3f",
"target": {
"type": "segment",
"segment": "beta"
},
"campaign": "changelog-2026-03"
}
{
"messageIds": [
"1731837600000-2",
"1731837600000-3"
],
"notificationIdsBase": "order-99214",
"batchSize": 2
}
{
"error": "validation_error",
"issues": [
{
"path": "",
"message": "Invalid input: expected object, received undefined"
}
]
}
{
"error": "validation_error",
"issues": [
{
"path": "template",
"message": "Invalid input: expected string, received undefined"
}
]
}
{
"error": "validation_error",
"issues": [
{
"path": "user",
"message": "one of `user`, `segment`, or `topic` is required"
}
]
}
{
"error": "validation_error",
"issues": [
{
"path": "user",
"message": "provide exactly one of `user`, `segment`, or `topic`"
}
]
}
{
"error": "validation_error",
"issues": [
{
"path": "channels.0",
"message": "Invalid option: expected one of \"email\"|\"sms\"|\"push\"|\"webhook\"|\"in-app\"|\"telegram\"|\"discord\"|\"whatsapp\"|\"slack\""
}
]
}
{
"error": "validation_error",
"issues": [
{
"path": "sendAt",
"message": "Invalid ISO datetime"
}
]
}
Common errors (401, 400, 403, 429, 413, 500)
{
"error": "unauthorized",
"message": "Invalid or missing API key"
}
{
"error": "bad_request",
"message": "x-project-id header or projectId query param required when using admin token"
}
{
"error": "forbidden",
"message": "API key is read-only"
}
{
"error": "too_many_requests",
"message": "Project rate limit exceeded (max 600 req/min)"
}
{
"error": "malformed_json",
"message": "malformed_json"
}
{
"error": "payload_too_large",
"message": "payload_too_large"
}
{
"error": "internal_error"
}
Example
curl -X POST http://localhost:3000/v1/notify \
-H "Authorization: Bearer $NK_KEY" \
-H "Content-Type: application/json" \
-H "x-idempotency-key: order-99214" \
-d '{
"user": "usr_123",
"template": "order-confirmed",
"channels": ["email", "push"],
"data": { "orderId": "99214" }
}'
await notifkit.notify({
user: "usr_123",
template: "order-confirmed",
channels: ["email", "push"],
data: { orderId: "99214" },
});
Get a task's status
GET/v1/notifications/{taskId}
Auth: Project key, or the admin key or a session with x-project-id.
Every log row for one task, newest first. status is the newest row's status, so it can be an engagement event such as opened.
Path parameters
| Name | Type | Description |
|---|---|---|
taskId | string | Task id from the delivery log. |
Responses
{
"status": "opened",
"logs": [
{
"id": "8e2a3b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
"projectId": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"taskId": "7e0d3f2a-1b4c-4d5e-8f60-7a8b9c0d1e2f:41a9e6b2-3c4d-4e5f-9a6b-7c8d9e0f1a2b",
"providerMessageId": "4f1e8b7c-2d3a-4e5b-9c6d-0a1b2c3d4e5f",
"templateId": "order-confirmed",
"workflowInstanceId": null,
"channel": "email",
"attempt": 0,
"kind": "opened",
"status": "opened",
"campaignId": null,
"metadata": null,
"timestamp": "2026-11-17T10:04:37.551Z"
},
{
"id": "6c1f2e3d-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"projectId": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"taskId": "7e0d3f2a-1b4c-4d5e-8f60-7a8b9c0d1e2f:41a9e6b2-3c4d-4e5f-9a6b-7c8d9e0f1a2b",
"providerMessageId": "4f1e8b7c-2d3a-4e5b-9c6d-0a1b2c3d4e5f",
"templateId": "order-confirmed",
"workflowInstanceId": null,
"channel": "email",
"attempt": 1,
"kind": "attempt",
"status": "delivered",
"campaignId": null,
"metadata": null,
"timestamp": "2026-11-17T10:00:01.204Z"
},
{
"id": "5b0e1d2c-3f4a-4b5c-9d6e-7f8a9b0c1d2e",
"projectId": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"taskId": "7e0d3f2a-1b4c-4d5e-8f60-7a8b9c0d1e2f:41a9e6b2-3c4d-4e5f-9a6b-7c8d9e0f1a2b",
"providerMessageId": null,
"templateId": "order-confirmed",
"workflowInstanceId": null,
"channel": "email",
"attempt": 1,
"kind": "dispatched",
"status": "dispatched",
"campaignId": null,
"metadata": null,
"timestamp": "2026-11-17T10:00:00.912Z"
}
]
}
{
"error": "not_found",
"message": "Task not found or not processed yet"
}
Common errors (401, 400, 429, 500)
{
"error": "unauthorized",
"message": "Invalid or missing API key"
}
{
"error": "bad_request",
"message": "x-project-id header or projectId query param required when using admin token"
}
{
"error": "too_many_requests",
"message": "Project rate limit exceeded (max 600 req/min)"
}
{
"error": "internal_error"
}
Example
curl http://localhost:3000/v1/notifications/7e0d3f2a-1b4c-4d5e-8f60-7a8b9c0d1e2f:41a9e6b2-3c4d-4e5f-9a6b-7c8d9e0f1a2b -H "Authorization: Bearer $NK_KEY"
const { status, logs } = await notifkit.getNotificationStatus(taskId);
Cancel a scheduled task
DELETE/v1/notifications/{taskId}
Auth: Project key with the admin role, or the admin key or a writable session with x-project-id.
Cancels a task that is still waiting: a sendAt send, a quiet-hours deferral or a retry. Once released for delivery it can't be recalled.
Path parameters
| Name | Type | Description |
|---|---|---|
taskId | string | Task id from the scheduled list. |
Responses
{
"success": true
}
{
"error": "not_found",
"message": "Task not found or already processed"
}
Common errors (401, 400, 403, 429, 500)
{
"error": "unauthorized",
"message": "Invalid or missing API key"
}
{
"error": "bad_request",
"message": "x-project-id header or projectId query param required when using admin token"
}
{
"error": "forbidden",
"message": "API key is read-only"
}
{
"error": "too_many_requests",
"message": "Project rate limit exceeded (max 600 req/min)"
}
{
"error": "internal_error"
}
Example
curl -X DELETE http://localhost:3000/v1/notifications/7e0d3f2a-1b4c-4d5e-8f60-7a8b9c0d1e2f:41a9e6b2-3c4d-4e5f-9a6b-7c8d9e0f1a2b -H "Authorization: Bearer $NK_KEY"
await notifkit.cancelNotification(taskId);
List scheduled tasks
GET/v1/notifications/scheduled
Auth: Project key, or the admin key or a session with x-project-id.
Tasks waiting for a future send time, ordered by task id. payload is the full task with its scheduledAt. Optional fields (campaignId, fallbackChain, workflowInstanceId, deliveryOptions.headers, deliveryAttemptCount) appear only when set.
Query parameters
| Name | Type | Default | Description |
|---|---|---|---|
limit | number | 50 | 1 to 100. |
cursor | string | nextCursor from the previous page. | |
channel | string | Only this channel. |
Responses
{
"scheduled": [
{
"taskId": "7e0d3f2a-1b4c-4d5e-8f60-7a8b9c0d1e2f:41a9e6b2-3c4d-4e5f-9a6b-7c8d9e0f1a2b",
"payload": {
"projectId": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"taskId": "7e0d3f2a-1b4c-4d5e-8f60-7a8b9c0d1e2f:41a9e6b2-3c4d-4e5f-9a6b-7c8d9e0f1a2b",
"enrichedEventId": "3a9b8c7d-6e5f-4a3b-9c2d-1e0f9a8b7c6d",
"recipientId": "usr_123",
"channel": "email",
"priority": "normal",
"templateId": "order-confirmed",
"templateVariables": {
"orderId": "99214"
},
"recipient": {
"id": "usr_123",
"email": "[email protected]",
"locale": "en",
"timezone": "America/New_York",
"preferences": {
"optedOut": false,
"channels": [],
"quietHours": [
{
"start": "22:00",
"end": "08:00"
}
]
}
},
"destination": "[email protected]",
"deliveryOptions": {
"maxAttempts": 3,
"timeoutMs": 10000
},
"scheduledAt": "2026-11-18T13:00:00.000Z"
},
"createdAt": "2026-11-17T10:00:00.000Z"
}
],
"nextCursor": "7e0d3f2a-1b4c-4d5e-8f60-7a8b9c0d1e2f:41a9e6b2-3c4d-4e5f-9a6b-7c8d9e0f1a2b"
}
{
"scheduled": [],
"nextCursor": null
}
Common errors (401, 400, 429, 500)
{
"error": "unauthorized",
"message": "Invalid or missing API key"
}
{
"error": "bad_request",
"message": "x-project-id header or projectId query param required when using admin token"
}
{
"error": "too_many_requests",
"message": "Project rate limit exceeded (max 600 req/min)"
}
{
"error": "internal_error"
}
Example
curl "http://localhost:3000/v1/notifications/scheduled?limit=20" -H "Authorization: Bearer $NK_KEY"
const { scheduled } = await notifkit.getScheduledMessages();
The client method takes no options and returns the first page.
Read the delivery log
GET/v1/notifications/logs
Auth: Project key, or the admin key or a session with x-project-id.
One entry per task, newest first, showing its latest outcome. Skipped sends (opted out, throttled, suppressed) never reach the log, and failed rows don't carry the error text. status is dispatched, delivered, failed, or an engagement event (opened, clicked, bounced, complained, unsubscribed). metadata is set only on engagement rows, for example the clicked URL.
Query parameters
| Name | Type | Default | Description |
|---|---|---|---|
limit | number | 50 | 1 to 100. |
cursor | string | nextCursor from the previous page. | |
templateId | string | Only this template. | |
channel | string | Only this channel. | |
status | string | Only this status. | |
taskId | string | Only this task. | |
workflowInstanceId | string | Only sends from this workflow instance. | |
campaign | string | Only this campaign label. | |
search | string | Substring of the task id, template id, provider message id or campaign. |
Responses
{
"logs": [
{
"id": "8e2a3b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
"projectId": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"taskId": "7e0d3f2a-1b4c-4d5e-8f60-7a8b9c0d1e2f:41a9e6b2-3c4d-4e5f-9a6b-7c8d9e0f1a2b",
"providerMessageId": "4f1e8b7c-2d3a-4e5b-9c6d-0a1b2c3d4e5f",
"templateId": "order-confirmed",
"workflowInstanceId": null,
"channel": "email",
"attempt": 0,
"kind": "opened",
"status": "opened",
"campaignId": null,
"metadata": null,
"timestamp": "2026-11-17T10:04:37.551Z"
},
{
"id": "9f3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
"projectId": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"taskId": "7e0d3f2a-1b4c-4d5e-8f60-7a8b9c0d1e2f:52b0f7c3-4d5e-4f6a-8b7c-9d0e1f2a3b4c",
"providerMessageId": "projects/acme/messages/0:1731837601204%31bd1c9631bd1c96",
"templateId": "order-confirmed",
"workflowInstanceId": null,
"channel": "push",
"attempt": 1,
"kind": "attempt",
"status": "failed",
"campaignId": null,
"metadata": null,
"timestamp": "2026-11-17T10:00:01.380Z"
}
],
"nextCursor": "WyIyMDI2LTExLTE3IDEwOjAwOjAxLjM4KzAwIiwiOWYzYjRjNWQtNmU3Zi00YThiLTljMGQtMWUyZjNhNGI1YzZkIl0"
}
{
"logs": [],
"nextCursor": null
}
Common errors (401, 400, 429, 500)
{
"error": "unauthorized",
"message": "Invalid or missing API key"
}
{
"error": "bad_request",
"message": "x-project-id header or projectId query param required when using admin token"
}
{
"error": "too_many_requests",
"message": "Project rate limit exceeded (max 600 req/min)"
}
{
"error": "internal_error"
}
Example
curl "http://localhost:3000/v1/notifications/logs?channel=email&status=failed" -H "Authorization: Bearer $NK_KEY"
const { logs, nextCursor } = await notifkit.getNotificationLogs({ channel: "email", status: "failed" });