Notify API reference

Notify API · Notification-Types

post/v1/workspaces/{workspace_id}/notification-typesAuth

Create a notification type

At most 200 types per workspace during the preview. Add templates with `PUT …/templates/{channel}/{locale}`, or create the type and its templates in one call with `PUT /notification-types/by-key/{key}`.

Path parameters

workspace_id*string · uuid

Id of the workspace.

Headers

Idempotency-Keystring

A key (1..256 chars, [A-Za-z0-9._:-]) makes retries safe: a replay returns the original response for 24 h.

Request body

namestring

Display name.

Example: "Invoice paid"

descriptionstring

What the notification is for.

category_keystring

Key of the category the type belongs to.

Example: "billing"

routingobject

Which channels are tried, and in what order.

criticalboolean

Critical types (security notices) ignore opt-outs and quiet hours and use their own rate budget. They never bypass hard bounces, spam complaints or Mail suppression.

ttl_secondsinteger

Deliveries not sent within this many seconds expire.

default_localestring

Locale used when the recipient locale has no template (BCP 47).

Example: "en"

email_quiet_hoursboolean

Hold email during the recipient quiet hours too (push is always held, the inbox never).

throttleobject

Per-recipient cap for this type; null removes it.

key*string

Key used when sending, unique in the workspace: must start with a-z and use only a-z 0-9 _ . - (at most 100 characters).

Example: "invoice.paid"

Response · 201 Created.

id*string · uuid

Type id.

key*string

Key used when sending.

Example: "invoice.paid"

name*string

Display name.

description*string

Description.

category_id*string · uuid

Category id.

category_key*string

Category key.

routing*object

Routing.

critical*boolean

Whether the type is critical.

ttl_seconds*integer

Time to live of a delivery, in seconds.

default_locale*string

Fallback locale.

email_quiet_hours*boolean

Whether email is held during quiet hours.

throttle*object

Per-recipient cap.

archived_at*string · date-time

When archived; archived types cannot be sent.

version*integer

Increases on every change of the type.

templates*array

The templates (bodies under `…/templates/{channel}/{locale}`).

created_at*string · date-time

Created.

updated_at*string · date-time

Last change.

Example

Request

POST https://api.notify.productcraft.co/v1/workspaces/{workspace_id}/notification-types
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "name": "Invoice paid",
  "description": "string",
  "category_key": "billing",
  "routing": {},
  "critical": false,
  "ttl_seconds": 0,
  "default_locale": "en",
  "email_quiet_hours": false,
  "throttle": {},
  "key": "invoice.paid"
}

Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "key": "invoice.paid",
  "name": "string",
  "description": "string",
  "category_id": "00000000-0000-0000-0000-000000000000",
  "category_key": "string",
  "routing": {},
  "critical": false,
  "ttl_seconds": 0,
  "default_locale": "string",
  "email_quiet_hours": false,
  "throttle": {},
  "archived_at": "2026-01-01T00:00:00.000Z",
  "version": 0,
  "templates": [
    {
      "channel": {},
      "locale": "pt-PT",
      "version": 0,
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}