Skip to main content

Sending notifications

Template-based request​

Requires notifications:send and a published template matching the requested channel and locale.

POST /v1/notifications
Authorization: Bearer APPLICATION_API_KEY
Content-Type: application/json
Idempotency-Key: invoice-paid-INV-10001-v1
{
  "account_key": "org-123",
  "event_key": "billing.invoice.paid",
  "recipient": {
    "external_user_id": "user-42",
    "email": "user@example.com"
  },
  "channels": ["email", "in_app"],
  "template_key": "invoice.paid",
  "locale": "en-US",
  "variables": {
    "invoice_number": "INV-10001",
    "amount": 125000
  }
}

This example needs an email provider on org-123 and published versions for both channels. event_key is your business event name; template_key selects content. They are separate fields.

Raw content​

To send subject and body directly without a template, the credential needs both notifications:send and notifications:send_raw. See the Quickstart.

Specify the locale explicitly. Notify currently defaults an omitted locale to id-ID; use en-US when your published template and content are English. Documentation language does not change API locale defaults.

Channel selection​

Supply channels explicitly or omit them when an active routing rule matches event_key. Without explicit channels or a matching route, the request is rejected.

Idempotency​

The key is required and identifies one intended message within the application, customer account, and environment. Keep the same payload and key for retries. A duplicate returns the existing notification; a changed payload with the same key returns 409.

Use a stable event ID, message type, recipient discriminator when needed, and version. If one business event sends separate requests to several recipients, each intended message needs a distinct key.

Delivery status​

HTTP 202 means accepted for asynchronous processing. Save the response id and read GET /v1/notifications/{id} with notifications:read to inspect per-channel delivery outcomes.

A successful provider submission is not proof that a person has read a message. Status detail depends on the channel and provider.

Manual retry​

POST /v1/deliveries/{id}/retry requires notifications:send. The current API accepts terminal states failed, dead, or expired. Fix the underlying configuration first and inspect expiry constraints. Repeating a delivery may produce another external send; use it as an explicit operational action rather than creating another notification for the same event.