Skip to main content
POST
Send a direct notification to a specific recipient or send a broadcast to all recipients subscribed to a target.
  • Direct: If recipient_id is set, target is optional.
  • Broadcast: If recipient_id is null, target is required.
A send must carry at least one content block — payload for in-app, email for email. Omitting both returns a 400, since such a send names no medium.
Sending is asynchronous. A direct send returns as soon as the notification is accepted — the response carries the notification id with status: "enqueued". Preference gating, quota, and email are all resolved by a background worker. Read the resolved outcome back with retrieve a notification.

​
Delivering email

Include the optional typed email block (subject, html, text) to also send an email. Its presence is your “email is eligible” signal — omit it and no email is sent (there is no fallback that derives an email from payload). See mediums for the full model.
  • Direct sends only. An email block on a broadcast returns 400.
  • No templating. You render the subject/HTML/text yourself (e.g. with @react-email) and pass the result. text is optional and derived from html when omitted.
  • Email fires only when the (target, email) pair is cataloged, the recipient’s email preference is enabled, and the recipient has a primary email contact. Otherwise the send still succeeds and the email is skipped.
  • The email is delivered by a background worker, so its outcome is not on the send response. Read it back on the notification’s email field via retrieve a notification.

​
Email without an in-app notification

On a direct send, payload is optional. Omit it and Bodhveda sends the email without creating an in-app notification — useful when the two mediums want different timing (an instant in-app row per event, but one debounced email covering several).
The notification is still created and still returns an id — you need one to read the email outcome back — but its status is not_requested and it is excluded from the recipient’s feed, their unread count, and mark-all-read. The recipient’s in-app preference does not apply to it; the email gates above still do. An explicit "payload": null is treated the same as omitting it. payload remains required on a broadcast.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer bv_xxxxxxxxx, where bv_xxxxxxxxx is your API Key with Full access scope.

Body

application/json
​
recipient_id
string | null

The id of a recipient.

  • If null → this is treated as a broadcast notification.
  • If set → this is a direct notification to that recipient.

💡 If no recipient exists with the recipient_id, Bodhveda will create a new recipient with that recipient_id.

​
target
object

A target is the structure used to describe who should get a notification and how it should be categorized.

​
payload
object | null

Arbitrary JSON payload for the notification. This is the in-app content block — its presence is what makes the notification eligible for in-app delivery.

Optional on a direct send. Omit it to deliver on email without creating an in-app notification (an email-only send) — the email block then stands alone. An explicit null counts as omitted.

Required on a broadcast, which is in-app only.

⚠️ A send must carry at least one content block. Omitting both payload and email is a 400 — such a send names no medium.

​
email
object

Optional typed email content block. Its presence is your signal that email is eligible for this send (content-block-implies-intent). Absence ⇒ no email — there is no fallback that derives email from payload.

  • Direct sends only. Including an email block on a broadcast returns 400 (email is never sent on broadcasts).
  • Bodhveda does no templating in v1 — you render your own subject/HTML/text (e.g. with @react-email) and pass the result.
  • Email still fires only if the (target, email) pair is in the project catalog, the recipient's email preference is enabled, and the recipient has a primary email contact.

Response

200 - application/json

Notification response