Send Notification

POST 
/notifications-srv/notifications

Sends a template-based notification to one or more recipients through a supported communication channel: email, SMS, IVR, push, or chat.

Quick start

1. Set criteria (templateKey, groupId, commMethod, optional locale) to select a published, enabled template.
2. Pass placeholder values in systemAttributes / customAttributes / contextAttributes (root and/or per recipient).
3. Omit request content.subject and content.content for normal template sends — the server renders them from the template.
4. Check each recipient’s status in the 200 response (SUCCESS, FAILED, or SKIPPED).

Important: Subject and body come from the matched template, rendered with your attributes (Handlebars). Do not put HTML in content.content or content.data.htmlContent expecting it to be the email body. To send pre-built HTML, put it in an attribute (for example customAttributes.htmlContent) and use {{{htmlContent}}} in the template. See Communication templates — How content is built.

---

Template resolution (criteria)

Field	Required	Description
templateKey	Yes	Template type / action key (e.g. VERIFY_USER, INACTIVE_USER)
groupId	Yes	Template group (sender, provider, and group defaultLocale)
commMethod	Yes	email, sms, ivr, push, or chat
locale	No	Preferred locale (e.g. en, de-DE). If omitted or unmatched, fallback applies
processingType	No	Exact match when set (LINK, CODE, GENERAL, …); omitted = not filtered
usageType	No	Exact match when set; omitted = not filtered
verificationType	No	Exact match when set; omitted = not filtered
number	No	Reminder sequence (1–5); advanced opt-in reminder flows

Locale fallback (when selecting a template row): exact criteria.locale → locale prefix variants → template group defaultLocale → tenant instance default locale.

criteria.defaultLocale is not used for normal template lookup. Configure fallback on the template group instead.

Discover allowed attributes for a key via template type attributes / group template filters.

---

Rendering (attributes → subject / body)

Placeholder values are merged into one flat map (later keys win):

1. Root systemAttributes → customAttributes → contextAttributes
2. Then that recipient’s systemAttributes → customAttributes → contextAttributes

Syntax: {{name}} (escaped) and {{{htmlContent}}} (raw HTML). Required attributes are validated on the merged map per recipient. Keys not allowed on the template type may be stripped from root attributes.

Root attributes work for single and multiple recipients (defaults). Recipient values override the same keys.

Attribute bag	Typical use
systemAttributes	Profile fields allowed by the template type (given_name, email, code, …)
customAttributes	App / developer placeholders (e.g. htmlContent, subject, custom fields)
contextAttributes	Request context (client_id, device_id, sub, …)

---

Request field roles

Field	Role
criteria	Selects the template row
Attribute bags	Fill {{…}} / {{{…}}} in the template
content.subject / content.content / content.messageFormat	Ignored / overwritten after template render on template-based sends
content.data	Channel-specific payload (mainly push); does not drive email/SMS subject or body

---

Draft vs disabled templates

Template state	Behavior
Draft (isDraft: true)	Excluded from selection. Service tries the next locale match. 400 if no published template matches.
Disabled (enabled: false)	May still be selected. HTTP 200 with per-recipient status: SKIPPED and a reason.

Publish and enable templates before relying on them in production.

---

Recipients (recipientAddresses)

• Single recipient requests must contain exactly 1 entry.
• Multiple recipient requests support up to 100 entries.

Each entry needs address (and usually name) plus any per-recipient attributes.

---

Sender overrides

If senderName, senderAddress, or replyAddress are omitted, the API falls back to the communication group settings (groupId) or the communication provider configuration.

---

Channel-specific content.data (push)

For email, SMS, IVR, chat, omit content.data (or set it to null). It does not supply the message body.

For push, optional fields include:

Field	Type	Description
data	map[string]string	Silent key-value pairs for the app
topic	string	Topic fan-out instead of individual tokens
image_url	string	Rich notification image URL
priority	string	high or normal (default)
click_action	string	Deep link / intent on tap
analytics_label	string	Analytics segmentation label
validate_only	boolean	Validate with the provider without delivering

---

Attachments

File attachments require Content-Type: multipart/form-data (email only):

Field	Description
attachment	A single file
attachments	Multiple files

Other body fields (criteria, recipientAddresses, …) must be included as form parts in the same multipart request.

Request

Responses

200

OK — Notification dispatched. Check data[].status for per-recipient delivery outcome.

400

Bad Request — returned when request validation fails, required attributes are missing, no matching published template is found, the template type is unknown, or the rendered email subject is empty.

401

Unauthorized

Response Headers

header-0