Star
API reference

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

FieldTypeRequiredDescription
templatesobject[]yesAt least one.
templates[].idstringyes
templates[].channelstringyesThe channel this content is for.
templates[].topicstring or string[]noTopics users can opt out of. None means transactional: no opt-out, no unsubscribe header. Stored as topics.
templates[].contentobjectyesKeys the transport reads.
templates[].aiPromptsobjectnoVariable 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

NameTypeDefaultDescription
channelstringOnly this channel.
topicstringOnly templates with this topic.
limitnumberall1 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

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

NameTypeDescription
idstringTemplate 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");