Templates
A template is content for one channel. Keep templates in your repository and sync the whole set on deploy.
The template object
{
"id": "order-confirmed",
"channel": "email",
"content": {
"subject": "Order {{orderId}} confirmed",
"text": "Thanks! Your order {{orderId}} is confirmed.",
"html": "<p>Thanks! Your order <b>{{orderId}}</b> is confirmed.</p>"
},
"topics": [],
"aiPrompts": null
}
content is free-form. First-party transports read subject, text (or body) and html (or htmlBody), and email reads from and replyTo. Placeholders are {{name}}, escaped for the field they land in. See Templates & AI. aiPrompts is null when unset.
Sync templates
PUT/v1/templates
Auth: Project key with the admin role, or the admin key or a writable session with x-project-id.
Upserts every template in the list by id, replacing its channel, topics, content and prompts. Templates not in the list are left alone. Workers pick up the change on the next message. synced is the number of templates you sent.
Body
| Field | Type | Required | Description |
|---|---|---|---|
templates | object[] | yes | At least one. |
templates[].id | string | yes | |
templates[].channel | string | yes | The channel this content is for. |
templates[].topic | string or string[] | no | Topics users can opt out of. None means transactional: no opt-out, no unsubscribe header. Stored as topics. |
templates[].content | object | yes | Keys the transport reads. |
templates[].aiPrompts | object | no | Variable name to prompt. |
Responses
{
"synced": 1
}
{
"error": "validation_error",
"issues": [
{
"path": "templates",
"message": "Too small: expected array to have >=1 items"
}
]
}
{
"error": "validation_error",
"issues": [
{
"path": "templates.0.content",
"message": "Invalid input: expected record, received undefined"
}
]
}
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 PUT http://localhost:3000/v1/templates \
-H "Authorization: Bearer $NK_KEY" \
-H "Content-Type: application/json" \
-d '{
"templates": [{
"id": "order-confirmed",
"channel": "email",
"content": { "subject": "Order {{orderId}} confirmed", "text": "Thanks!" }
}]
}'
await notifkit.syncTemplates([
{
id: "order-confirmed",
channel: "email",
content: { subject: "Order {{orderId}} confirmed", text: "Thanks!" },
},
]);
Or pass templates to the client constructor and call sync().
List templates
GET/v1/templates
Auth: Project key, or the admin key or a session with x-project-id.
Query parameters
| Name | Type | Default | Description |
|---|---|---|---|
channel | string | Only this channel. | |
topic | string | Only templates with this topic. | |
limit | number | all | 1 to 100. |
Responses
{
"templates": [
{
"id": "order-confirmed",
"channel": "email",
"content": {
"subject": "Order {{orderId}} confirmed",
"text": "Thanks! Your order {{orderId}} is confirmed.",
"html": "<p>Thanks! Your order <b>{{orderId}}</b> is confirmed.</p>"
},
"topics": [],
"aiPrompts": null
},
{
"id": "weekly-digest",
"channel": "email",
"content": {
"subject": "Your week",
"text": "{{summary}}"
},
"topics": [
"marketing"
],
"aiPrompts": {
"summary": "Summarise this week's activity for {{name}} in two sentences."
}
}
]
}
{
"templates": []
}
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/templates?channel=email" -H "Authorization: Bearer $NK_KEY"
const { templates } = await notifkit.listTemplates();
Get a template
GET/v1/templates/{id}
Auth: Project key, or the admin key or a session with x-project-id.
Path parameters
| Name | Type | Description |
|---|---|---|
id | string | Template id. |
Responses
{
"id": "order-confirmed",
"channel": "email",
"content": {
"subject": "Order {{orderId}} confirmed",
"text": "Thanks! Your order {{orderId}} is confirmed.",
"html": "<p>Thanks! Your order <b>{{orderId}}</b> is confirmed.</p>"
},
"topics": [],
"aiPrompts": null
}
{
"error": "template_not_found",
"id": "order-confirmed"
}
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/templates/order-confirmed -H "Authorization: Bearer $NK_KEY"
const template = await notifkit.getTemplate("order-confirmed");
Delete a template
DELETE/v1/templates/{id}
Auth: Project key with the admin role, or the admin key or a writable session with x-project-id.
Sends still queued with this template are dropped as template_not_found, or fail at delivery.
Path parameters
| Name | Type | Description |
|---|---|---|
id | string | Template id. |
Responses
No body.
{
"error": "template_not_found",
"id": "order-confirmed"
}
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/templates/order-confirmed -H "Authorization: Bearer $NK_KEY"
await notifkit.deleteTemplate("order-confirmed");