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
}
]
}
| Field | Notes |
|---|---|
language | Default en. |
timezone | IANA name, like America/New_York or UTC. Abbreviations like EST are rejected. Default UTC. |
email | Left out when the user has none. |
preferences.channels | Channel to true/false. false turns that channel off. |
preferences.topics | Topic to true/false. false blocks templates with that topic. true subscribes to topic sends. |
preferences.quietHours | HH:MM windows in the user's timezone. A window may wrap midnight. Left out when there are none. |
contacts[].active | false 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
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Your own user id. |
email | string or string[] | no | Email contacts. The first is also the user's email. |
phone | string or string[] | no | SMS contacts, in E.164. |
pushToken | string or string[] | no | Push contacts. |
contacts | object[] | no | { channel, target, preferences? } for any channel. Only preferences.topics is kept per contact. |
language | string | no | |
timezone | string | no | IANA name. |
segments | string[] | no | Tags to add. |
preferences | object | no | See 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
| Name | Type | Default | Description |
|---|---|---|---|
limit | number | 50 | 1 to 100. |
cursor | string | nextCursor from the previous page. | |
search | string | Substring of the user id or email. | |
segment | string | Only users with this tag. | |
channel | string | Only users with a contact on this channel. | |
language | string | Exact match. | |
timezone | string | Exact 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
| Name | Type | Description |
|---|---|---|
id | string | Your 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
| Name | Type | Description |
|---|---|---|
id | string | Your 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
| Name | Type | Description |
|---|---|---|
id | string | Your 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
| Name | Type | Description |
|---|---|---|
id | string | Your 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
| Name | Type | Description |
|---|---|---|
id | string | Your user id. |
Body
| Field | Type | Required | Description |
|---|---|---|---|
channel | string | yes | Any channel. |
target | string | yes | The address: email, E.164 number, push token, chat id or URL. |
preferences | object | no | Only 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
| Name | Type | Description |
|---|---|---|
id | string | Your 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
| Name | Type | Description |
|---|---|---|
id | string | Your user id. |
channel | string | Contact channel. |
target | string | The 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
| Name | Type | Description |
|---|---|---|
id | string | Your 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
| Name | Type | Description |
|---|---|---|
id | string | Your user id. |
Body
| Field | Type | Required | Description |
|---|---|---|---|
channels | object | no | Channel to boolean. |
topics | object | no | Topic to boolean. |
quietHours | object[] | 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();