Star
API reference

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

HeaderTypeDescription
x-idempotency-keystringDrops repeats of this key for 24 hours. With several users, each gets <key>-<index>.

Body

FieldTypeRequiredDescription
userstring, object or arrayone of threeA user id, an inline user (same fields as POST /v1/users, saved before sending), or an array of either.
segmentstringone of threeEvery user tagged with this segment.
topicstringone of threeEvery user whose preferences.topics[topic] is true.
templatestringyesTemplate id.
dataobjectnoValues for the template's {{placeholders}}.
channelsstring[]noDefault ["email"]. One of email, sms, push, slack, whatsapp, telegram, discord, webhook, in-app.
fallbackbooleannoDefault false, which sends on every channel. true tries them in order and stops at the first that delivers.
prioritystringnolow, normal (default), high or critical. critical skips quiet hours and the throttle. high shares the normal lane.
sendAtstringnoUTC date-time, like 2026-11-18T09:00:00Z. Offsets are rejected. It's one instant for everyone, not adjusted to each user's timezone.
campaignstringnoLabel for campaign stats, up to 128 characters.
aiPromptsobjectnoTemplate 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

NameTypeDescription
taskIdstringTask 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

NameTypeDescription
taskIdstringTask 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

NameTypeDefaultDescription
limitnumber501 to 100.
cursorstringnextCursor from the previous page.
channelstringOnly 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

NameTypeDefaultDescription
limitnumber501 to 100.
cursorstringnextCursor from the previous page.
templateIdstringOnly this template.
channelstringOnly this channel.
statusstringOnly this status.
taskIdstringOnly this task.
workflowInstanceIdstringOnly sends from this workflow instance.
campaignstringOnly this campaign label.
searchstringSubstring 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" });