/v1/workspaces/{workspace_id}/notificationsAuthSend 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 · uuidId of the workspace.
Headers
Idempotency-Key*stringRequired 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*stringThe notification type key.
Example: "invoice.paid"
recipients*arrayWho 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"}]
dataobjectTemplate 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"}
channelsarrayOnly these channels (a subset of the type's routing).
actorobjectWho caused the notification.
exclude_actorbooleanLeave the actor out of the recipients (default true when `actor.external_id` is set).
send_atstring · date-timeSend at this time instead of now (UTC, ISO 8601), at most the type TTL ahead. Not with `delay_seconds`.
delay_secondsintegerSend this many seconds from now (at most the type TTL). Not with `send_at`.
cancellation_keystringYour 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"
tenantstringYour tenant (organisation, team): inbox items can be filtered by it.
Example: "org_42"
tagsobjectUp 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_missingbooleanCreate a bare recipient for each unknown external id instead of skipping it.
dry_runbooleanPlan 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*booleanAlways true: nothing was stored or sent.
type*stringThe notification type key.
plan*arrayOne row per recipient, channel and target, in recipient order.
skipped*arrayRecipients 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": {}
}
]
}