Star
API reference

Users and contacts

A user is your own id plus the addresses and preferences notifkit needs to reach them.

The user object

{
  "userId": "usr_123",
  "language": "en",
  "timezone": "America/New_York",
  "email": "[email protected]",
  "segments": [
    "beta"
  ],
  "preferences": {
    "channels": {
      "sms": false
    },
    "topics": {
      "marketing": false
    },
    "quietHours": [
      {
        "start": "22:00",
        "end": "08:00"
      }
    ]
  },
  "contacts": [
    {
      "id": "41a9e6b2-3c4d-4e5f-9a6b-7c8d9e0f1a2b",
      "userId": "usr_123",
      "channel": "email",
      "target": "[email protected]",
      "preferences": {
        "topics": {}
      },
      "active": true
    },
    {
      "id": "52b0f7c3-4d5e-4f6a-8b7c-9d0e1f2a3b4c",
      "userId": "usr_123",
      "channel": "push",
      "target": "dJ3f9aQ2R7mK:APA91bH7xLq2VnW8zT4pYc6sE1uR9oK3jF5gD0aB8wN2mX7vC4tZ6yL1qP3iS5eU9rO0hG2kJ4fA6dW8bM1nV3cX5zQ7",
      "preferences": {
        "topics": {
          "marketing": false
        }
      },
      "active": false
    }
  ]
}
FieldNotes
languageDefault en.
timezoneIANA name, like America/New_York or UTC. Abbreviations like EST are rejected. Default UTC.
emailLeft out when the user has none.
preferences.channelsChannel to true/false. false turns that channel off.
preferences.topicsTopic to true/false. false blocks templates with that topic. true subscribes to topic sends.
preferences.quietHoursHH:MM windows in the user's timezone. A window may wrap midnight. Left out when there are none.
contacts[].activefalse once a provider reports the address dead. Adding the contact again re-activates it.

Create or update a user

POST/v1/users

Auth: Project key with the admin role, or the admin key or a writable session with x-project-id.

Upserts by id. Fields you leave out keep their stored values, segments are added (never removed), and topic and channel preferences merge key by key. quietHours is replaced when you send it, so [] clears it.

Body

FieldTypeRequiredDescription
idstringyesYour own user id.
emailstring or string[]noEmail contacts. The first is also the user's email.
phonestring or string[]noSMS contacts, in E.164.
pushTokenstring or string[]noPush contacts.
contactsobject[]no{ channel, target, preferences? } for any channel. Only preferences.topics is kept per contact.
languagestringno
timezonestringnoIANA name.
segmentsstring[]noTags to add.
preferencesobjectnoSee the user object above.

Responses

{
  "id": "usr_123"
}
{
  "error": "validation_error",
  "issues": [
    {
      "path": "id",
      "message": "Invalid input: expected string, received undefined"
    }
  ]
}
{
  "error": "validation_error",
  "issues": [
    {
      "path": "timezone",
      "message": "expected an IANA timezone, e.g. America/New_York"
    }
  ]
}
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/users \
  -H "Authorization: Bearer $NK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "usr_123",
    "email": "[email protected]",
    "timezone": "America/New_York",
    "preferences": { "quietHours": [{ "start": "22:00", "end": "08:00" }] }
  }'
await notifkit.addUser({
  id: "usr_123",
  email: "[email protected]",
  timezone: "America/New_York",
});

identify() is an alias. Both also accept (id, contacts, options).

List users

GET/v1/users

Auth: Project key, or the admin key or a session with x-project-id.

Newest first. Entries hold the profile only. createdAt is in milliseconds.

Query parameters

NameTypeDefaultDescription
limitnumber501 to 100.
cursorstringnextCursor from the previous page.
searchstringSubstring of the user id or email.
segmentstringOnly users with this tag.
channelstringOnly users with a contact on this channel.
languagestringExact match.
timezonestringExact match.

Responses

{
  "users": [
    {
      "userId": "usr_124",
      "language": "en",
      "timezone": "UTC",
      "createdAt": 1731837660000
    },
    {
      "userId": "usr_123",
      "language": "en",
      "timezone": "America/New_York",
      "email": "[email protected]",
      "createdAt": 1731837600000
    }
  ],
  "nextCursor": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70"
}
{
  "users": [],
  "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/users?segment=beta&limit=2" -H "Authorization: Bearer $NK_KEY"
const { users, nextCursor } = await notifkit.listUsers({ segment: "beta", limit: 2 });

Get a user

GET/v1/users/{id}

Auth: Project key, or the admin key or a session with x-project-id.

Path parameters

NameTypeDescription
idstringYour user id.

Responses

{
  "userId": "usr_123",
  "language": "en",
  "timezone": "America/New_York",
  "email": "[email protected]",
  "segments": [
    "beta"
  ],
  "preferences": {
    "channels": {
      "sms": false
    },
    "topics": {
      "marketing": false
    },
    "quietHours": [
      {
        "start": "22:00",
        "end": "08:00"
      }
    ]
  },
  "contacts": [
    {
      "id": "41a9e6b2-3c4d-4e5f-9a6b-7c8d9e0f1a2b",
      "userId": "usr_123",
      "channel": "email",
      "target": "[email protected]",
      "preferences": {
        "topics": {}
      },
      "active": true
    },
    {
      "id": "52b0f7c3-4d5e-4f6a-8b7c-9d0e1f2a3b4c",
      "userId": "usr_123",
      "channel": "push",
      "target": "dJ3f9aQ2R7mK:APA91bH7xLq2VnW8zT4pYc6sE1uR9oK3jF5gD0aB8wN2mX7vC4tZ6yL1qP3iS5eU9rO0hG2kJ4fA6dW8bM1nV3cX5zQ7",
      "preferences": {
        "topics": {
          "marketing": false
        }
      },
      "active": false
    }
  ]
}
{
  "error": "user_not_found",
  "id": "usr_123"
}
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/users/usr_123 -H "Authorization: Bearer $NK_KEY"
const user = await notifkit.getUser("usr_123");

Get a user with recent sends

GET/v1/users/{id}/details

Auth: Project key, or the admin key or a session with x-project-id.

The user object plus logs: up to 50 of the newest delivery-log rows for the user's addresses, every row rather than one per task.

Path parameters

NameTypeDescription
idstringYour user id.

Responses

{
  "userId": "usr_123",
  "language": "en",
  "timezone": "America/New_York",
  "email": "[email protected]",
  "segments": [
    "beta"
  ],
  "preferences": {
    "channels": {
      "sms": false
    },
    "topics": {
      "marketing": false
    },
    "quietHours": [
      {
        "start": "22:00",
        "end": "08:00"
      }
    ]
  },
  "contacts": [
    {
      "id": "41a9e6b2-3c4d-4e5f-9a6b-7c8d9e0f1a2b",
      "userId": "usr_123",
      "channel": "email",
      "target": "[email protected]",
      "preferences": {
        "topics": {}
      },
      "active": true
    }
  ],
  "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": "user_not_found",
  "id": "usr_123"
}
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/users/usr_123/details -H "Authorization: Bearer $NK_KEY"
const { logs } = await notifkit.getUserDetails("usr_123");

Update a user

PATCH/v1/users/{id}

Auth: Project key with the admin role, or the admin key or a writable session with x-project-id.

Same fields as create, without id. Unlike create, segments replaces the whole list. Preferences merge the same way, and new contacts are added without removing existing ones.

Path parameters

NameTypeDescription
idstringYour user id.

Responses

{
  "id": "usr_123"
}
{
  "error": "validation_error",
  "issues": [
    {
      "path": "timezone",
      "message": "expected an IANA timezone, e.g. America/New_York"
    }
  ]
}
{
  "error": "user_not_found",
  "id": "usr_123"
}
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 PATCH http://localhost:3000/v1/users/usr_123 \
  -H "Authorization: Bearer $NK_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "segments": ["beta", "enterprise"] }'
await notifkit.updateUser("usr_123", { segments: ["beta", "enterprise"] });

Delete a user

DELETE/v1/users/{id}

Auth: Project key with the admin role, or the admin key or a writable session with x-project-id.

Deletes the user with their contacts, segments and preferences. Suppressions are kept, because they belong to the address.

Path parameters

NameTypeDescription
idstringYour user id.

Responses

No body.
{
  "error": "user_not_found",
  "id": "usr_123"
}
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/users/usr_123 -H "Authorization: Bearer $NK_KEY"
await notifkit.deleteUser("usr_123");

Add contacts

POST/v1/users/{id}/contacts

Auth: Project key with the admin role, or the admin key or a writable session with x-project-id.

Adds one contact, or an array of them. An existing contact is re-activated.

Path parameters

NameTypeDescription
idstringYour user id.

Body

FieldTypeRequiredDescription
channelstringyesAny channel.
targetstringyesThe address: email, E.164 number, push token, chat id or URL.
preferencesobjectnoOnly topics is stored per contact.

Responses

{
  "userId": "usr_123",
  "channel": "sms",
  "target": "+15551234567"
}
{
  "userId": "usr_123",
  "contacts": [
    {
      "channel": "sms",
      "target": "+15551234567"
    },
    {
      "channel": "push",
      "target": "dJ3f9aQ2R7mK:APA91bH7xLq2VnW8zT4pYc6sE1uR9oK3jF5gD0aB8wN2mX7vC4tZ6yL1qP3iS5eU9rO0hG2kJ4fA6dW8bM1nV3cX5zQ7"
    }
  ]
}
{
  "error": "validation_error",
  "issues": [
    {
      "path": "",
      "message": "Invalid input"
    }
  ]
}
{
  "error": "user_not_found",
  "id": "usr_123"
}
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/users/usr_123/contacts \
  -H "Authorization: Bearer $NK_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "sms", "target": "+15551234567" }'
await notifkit.addContact("usr_123", { channel: "sms", target: "+15551234567" });
// several at once
await notifkit.addContacts("usr_123", [{ channel: "push", target: token }]);

List a user's contacts

GET/v1/users/{id}/contacts

Auth: Project key, or the admin key or a session with x-project-id.

Path parameters

NameTypeDescription
idstringYour user id.

Responses

{
  "contacts": [
    {
      "id": "41a9e6b2-3c4d-4e5f-9a6b-7c8d9e0f1a2b",
      "userId": "usr_123",
      "channel": "email",
      "target": "[email protected]",
      "preferences": {
        "topics": {}
      },
      "active": true
    },
    {
      "id": "52b0f7c3-4d5e-4f6a-8b7c-9d0e1f2a3b4c",
      "userId": "usr_123",
      "channel": "push",
      "target": "dJ3f9aQ2R7mK:APA91bH7xLq2VnW8zT4pYc6sE1uR9oK3jF5gD0aB8wN2mX7vC4tZ6yL1qP3iS5eU9rO0hG2kJ4fA6dW8bM1nV3cX5zQ7",
      "preferences": {
        "topics": {
          "marketing": false
        }
      },
      "active": false
    }
  ]
}
{
  "contacts": []
}
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/users/usr_123/contacts -H "Authorization: Bearer $NK_KEY"
const { contacts } = await notifkit.getUserContacts("usr_123");

Remove a contact

DELETE/v1/users/{id}/contacts/{channel}/{target}

Auth: Project key with the admin role, or the admin key or a writable session with x-project-id.

URL-encode the target. It must match exactly as stored.

Path parameters

NameTypeDescription
idstringYour user id.
channelstringContact channel.
targetstringThe address.

Responses

No body.
{
  "error": "invalid_channel",
  "channel": "fax"
}
{
  "error": "contact_not_found"
}
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/users/usr_123/contacts/email/alice%40example.com" -H "Authorization: Bearer $NK_KEY"
await notifkit.deleteContact("usr_123", "email", "[email protected]");

Get preferences

GET/v1/users/{id}/preferences

Auth: Project key, or the admin key or a session with x-project-id.

Path parameters

NameTypeDescription
idstringYour user id.

Responses

{
  "channels": {
    "sms": false
  },
  "topics": {
    "marketing": false
  },
  "quietHours": [
    {
      "start": "22:00",
      "end": "08:00"
    }
  ]
}
{
  "channels": {},
  "topics": {}
}
{
  "error": "user_not_found",
  "id": "usr_123"
}
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/users/usr_123/preferences -H "Authorization: Bearer $NK_KEY"
const prefs = await notifkit.getUserPreferences("usr_123");

Update preferences

PATCH/v1/users/{id}/preferences

Auth: Project key with the admin role, or the admin key or a writable session with x-project-id.

Merges channels and topics key by key, and replaces quietHours when sent. The response echoes what you sent, not the merged result.

Path parameters

NameTypeDescription
idstringYour user id.

Body

FieldTypeRequiredDescription
channelsobjectnoChannel to boolean.
topicsobjectnoTopic to boolean.
quietHoursobject[]no{ start, end } in HH:MM.

Responses

{
  "id": "usr_123",
  "preferences": {
    "topics": {
      "marketing": false
    }
  }
}
{
  "error": "validation_error",
  "issues": [
    {
      "path": "quietHours.0.start",
      "message": "expected HH:MM (24h, user's timezone)"
    }
  ]
}
{
  "error": "user_not_found",
  "id": "usr_123"
}
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 PATCH http://localhost:3000/v1/users/usr_123/preferences \
  -H "Authorization: Bearer $NK_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "topics": { "marketing": false } }'
await notifkit.updateUserPreferences("usr_123", { topics: { marketing: false } });

List segments

GET/v1/segments

Auth: Project key, or the admin key or a session with x-project-id.

Every distinct segment tag on the project's users, in no particular order.

Responses

{
  "segments": [
    "beta",
    "enterprise"
  ]
}
{
  "segments": []
}
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/segments -H "Authorization: Bearer $NK_KEY"
const { segments } = await notifkit.listSegments();