Notify
Package notify is transactional email and SMS, sent through your org's own provider credential.
Package notify is transactional email and SMS, sent through your org's own provider credential.
| Base URL | https://api.hanzo.ai |
| Operations | 4 |
| Auth | Authorization: Bearer $HANZO_API_KEY |
notify
GET /v1/notify/health
Reports that the notify send surface is mounted.
It is a pure liveness probe: it answers 200 whenever this subsystem is mounted and checks nothing downstream, so an "ok" here says the routes are reachable, not that any provider credential is configured. The body is notifyd's verbatim, so probes and clients that keyed on the standalone service keep working unchanged.
POST /v1/notify/send/email
Delivers one transactional email through the caller org's own provider credential.
It is the channel-pinned form of the generic send: identical in every respect except that the channel is fixed to email, OVERRIDING whatever the body names — so a body that says sms still goes out as mail. The provider is the org's own email credential from KMS (Twilio Email, then SMTP), resolved for the validated principal's org; an unauthenticated caller gets 401. Subject is carried on the email channel only.
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
body | string | — | Body is the message text, sent verbatim when present — the no-template path. |
channel | string | — | Channel selects the delivery channel, sms or email. |
event | string | — | Event is the event name, which doubles as the template id when TemplateID is empty — the IAM OTP path sends… |
provider | string | — | Provider pins a provider service name (twilio, plivo, twilio_email, mail). |
subject | string | — | Subject is the message subject, carried on the email channel only. |
sync | string | — | Sync must be exactly "true": delivery here is synchronous, and anything else answers 503 because the queue plane that… |
template_id | string | — | TemplateID selects a built-in template when Body is empty. |
template_vars | — | TemplateVars carries the values the selected template renders against, as a raw JSON object. | |
to | string[] | — | To is the destination address per recipient — a phone number for sms, an email address for email. |
POST /v1/notify/send/sms
Delivers one transactional SMS through the caller org's own provider credential.
It is the channel-pinned form of the generic send: identical in every respect except that the channel is fixed to sms, OVERRIDING whatever the body names — so a body that says email still goes out as a text message. The provider is the org's own SMS credential from KMS (Twilio, then Plivo), resolved for the validated principal's org; an unauthenticated caller gets 401.
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
body | string | — | Body is the message text, sent verbatim when present — the no-template path. |
channel | string | — | Channel selects the delivery channel, sms or email. |
event | string | — | Event is the event name, which doubles as the template id when TemplateID is empty — the IAM OTP path sends… |
provider | string | — | Provider pins a provider service name (twilio, plivo, twilio_email, mail). |
subject | string | — | Subject is the message subject, carried on the email channel only. |
sync | string | — | Sync must be exactly "true": delivery here is synchronous, and anything else answers 503 because the queue plane that… |
template_id | string | — | TemplateID selects a built-in template when Body is empty. |
template_vars | — | TemplateVars carries the values the selected template renders against, as a raw JSON object. | |
to | string[] | — | To is the destination address per recipient — a phone number for sms, an email address for email. |
POST /v1/notify/send
Delivers one transactional message by email or SMS through the caller org's own provider credential.
The channel comes from the body — sms or email — and the provider credential is read from KMS at orgs/<org>/notify/<service>/<key>, never from the environment. The org is the validated principal's, never a client-supplied value, so a caller can only ever send as their own tenant; an unauthenticated caller gets 401. Naming no provider picks the one whose credentials are actually configured (Twilio, then Plivo for SMS; Twilio Email, then SMTP for email) and fails closed when none is. Delivery is synchronous and per recipient: one recipient answers the bare {message_id,status} outcome, several answer the {items:[…]} envelope. A terminal provider failure is a 200 whose status is failed with the reason in error, never a transport error. sync=true is REQUIRED — an async dispatch answers 503, because the queue plane that would run it is owned elsewhere. The message body wins verbatim when present; otherwise template_id (or the event name) selects a built-in template rendered against template_vars.
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
body | string | — | Body is the message text, sent verbatim when present — the no-template path. |
channel | string | — | Channel selects the delivery channel, sms or email. |
event | string | — | Event is the event name, which doubles as the template id when TemplateID is empty — the IAM OTP path sends… |
provider | string | — | Provider pins a provider service name (twilio, plivo, twilio_email, mail). |
subject | string | — | Subject is the message subject, carried on the email channel only. |
sync | string | — | Sync must be exactly "true": delivery here is synchronous, and anything else answers 503 because the queue plane that… |
template_id | string | — | TemplateID selects a built-in template when Body is empty. |
template_vars | — | TemplateVars carries the values the selected template renders against, as a raw JSON object. | |
to | string[] | — | To is the destination address per recipient — a phone number for sms, an email address for email. |
How is this guide?