Notify API reference

Notify API · Notifications

post/v1/workspaces/{workspace_id}/notificationsAuth

Send a notification

Notifies up to 1,000 recipients with one notification type, across the type's channels (in-app inbox, email, push, web push), honouring each recipient's preferences. Returns 202 as soon as the send is stored; delivery happens in the background (see `GET /deliveries`). Unknown external ids do not fail the call: they are listed in `skipped` (`create_missing: true` creates them instead); the call fails only when no recipient can be notified. An `Idempotency-Key` is **required** (a deterministic one built from your event, such as `invoice.paid:inv_123`, is best; dots are fine): the same key and body return the same notification, even when retried much later; the same key with a different body is a 409. `dry_run: true` returns the plan per recipient and channel with the reason for every skip, and stores nothing (200, no key needed). Limits: 3,000 recipients per minute per workspace; 30 notifications per minute per recipient (critical types have a separate 30), beyond which deliveries are skipped as `rate_limited`.

Path parameters

workspace_id*string · uuid

Id of the workspace.

Headers

Idempotency-Key*string

Required unless `dry_run` is true. 1 to 256 characters of `A-Z a-z 0-9 . _ : -` (`invoice.paid:inv_123`); the same key with the same body returns the original notification. Any other character is a 400 that names it: a send is never dropped silently.

Request body

type*string

The notification type key.

Example: "invoice.paid"

recipients*array

Who to notify: up to 1,000 external ids, or objects with an `external_id` and profile fields (created or updated with the send). Unknown ids do not fail the call: they come back in `skipped` (pass `create_missing: true` to create bare recipients instead).

Example: ["user_123",{"external_id":"user_456","email":"a@example.com","locale":"pt-PT"}]

dataobject

Template variables, exactly as sent (keys are not re-cased). At most 16 KB as JSON.

Example: {"amount":"12.00","invoice_url":"https://example.com/i/123"}

channelsarray

Only these channels (a subset of the type's routing).

actorobject

Who caused the notification.

exclude_actorboolean

Leave the actor out of the recipients (default true when `actor.external_id` is set).

send_atstring · date-time

Send at this time instead of now (UTC, ISO 8601), at most the type TTL ahead. Not with `delay_seconds`.

delay_secondsinteger

Send this many seconds from now (at most the type TTL). Not with `send_at`.

cancellation_keystring

Your key for cancelling later without storing our id (`POST /notifications/cancel`): 1-255 characters of `A-Z a-z 0-9 . _ : @ | -`, so it can embed a type key and an id (`invite.sent:inv_77`).

Example: "invite.sent:inv_77"

tenantstring

Your tenant (organisation, team): inbox items can be filtered by it.

Example: "org_42"

tagsobject

Up to 10 string pairs, searchable in the message log (`GET /notifications?tag=key:value`). Keys: 1-64 of `A-Z a-z 0-9 _ . : -`.

Example: {"invoice":"inv_123"}

create_missingboolean

Create a bare recipient for each unknown external id instead of skipping it.

dry_runboolean

Plan and explain per recipient and channel without storing or sending anything (no `Idempotency-Key` needed, no rate limit used).

Response · 200 `dry_run`: the plan; nothing stored or sent.

dry_run*boolean

Always true: nothing was stored or sent.

type*string

The notification type key.

plan*array

One row per recipient, channel and target, in recipient order.

skipped*array

Recipients that would be left out.

Example

Request

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

{
  "type": "invoice.paid",
  "recipients": [
    "user_123",
    {
      "external_id": "user_456",
      "email": "a@example.com",
      "locale": "pt-PT"
    }
  ],
  "data": {
    "amount": "12.00",
    "invoice_url": "https://example.com/i/123"
  },
  "channels": [
    "inbox"
  ],
  "actor": {},
  "exclude_actor": false,
  "send_at": "2026-01-01T00:00:00.000Z",
  "delay_seconds": 0,
  "cancellation_key": "invite.sent:inv_77",
  "tenant": "org_42",
  "tags": {
    "invoice": "inv_123"
  },
  "create_missing": false,
  "dry_run": false
}

Response

{
  "dry_run": false,
  "type": "string",
  "plan": [
    {
      "recipient": "user_123",
      "channel": {},
      "decision": {},
      "reason": {},
      "explanation": "string",
      "target": "string",
      "fallback_step": 0,
      "not_before": "2026-01-01T00:00:00.000Z"
    }
  ],
  "skipped": [
    {
      "external_id": "user_999",
      "reason": {}
    }
  ]
}