Skip to main content

Send Notification

POST 
/api/v1/notifications/send

Queue a notification for delivery across one or more channels.

Request​

{
  "channels": ["email"],
  "to": ["alice@example.com", "bob@example.com"],
  "subject": "Launch deck ready for review",
  "body": "The updated deck is attached to the project workspace.",
  "body_html": "<p>The updated deck is attached to the project workspace.</p>"
}
FieldTypeRequiredDescription
channelsarray of stringsnoDelivery channels. Defaults to ["email"]. Unknown channels return HTTP 400.
toarray of stringsyesRecipient identifiers (email addresses for the email channel).
subjectstringyesMessage subject.
bodystringyesPlain-text body. For HTML-capable channels, this is used when body_html is omitted.
body_htmlstringnoHTML body. Only valid for channels that support HTML (e.g. email).

Authorisation​

  • JWT / API key: caller must have the SEND_NOTIFICATIONS permission (granted by default to Admin, Manager and Creator roles).
  • OAuth2: the access token must include the send_notifications scope.

Response (HTTP 202)​

{
  "data": {
    "notification_id": "c15d7c2e4a6d4f7fa7b2d2d0a1a6c2a0",
    "queued_at": "2026-04-22T12:34:56Z",
    "channels": ["email"],
    "accepted_recipients": { "email": ["alice@example.com"] },
    "rejected_recipients": {
      "email": [
        { "recipient": "bob@outside.com", "reason": "not_in_allow_list" }
      ]
    }
  }
}

Rejection reasons​

ReasonMeaning
invalid_emailThe string is not a syntactically valid email address.
not_in_allow_listRecipient is not the caller, not in the group, and domain not allowed.
max_recipients_exceededThe request contained more than 50 recipients for this channel.

Limits​

  • Maximum 50 recipients per channel per request.
  • One email task is queued per recipient (failures are isolated).

Request​

Responses​

Notification queued for delivery.