Skip to content

Notifications

Wire each realm to your own SMS, email and push providers, and craft the templates that carry one-time codes, magic links and alerts.

What it is

HelixIAM delivers messages — OTP codes, magic links, push challenges and account notices — through per-realm messaging providers that you configure from the console. Nothing is hard-wired to a single vendor: pick the driver that fits each channel.

Channel Drivers
SMS Twilio, HTTP gateway
Email SMTP, Cloudflare Email Service, HTTP relay, Log only (development: sends nothing)
Push Firebase (FCM), Apple (APNs)

SMTP relays and push hosts are restricted

An SMTP relay — a realm's provider, and the server-wide fallback helix.notification.smtp.* — passes the egress guard: a relay on a private or loopback address must be listed by the deployment in HELIX_EGRESS_ALLOWED_PRIVATE_HOSTS (preferably as host:port, e.g. mailer.mail.svc.cluster.local:587), and ports other than 25, 465, 587 and 2525 in HELIX_MESSAGING_SMTP_ALLOWED_PORTS (e.g. 1025,8025-8030). Otherwise a send fails with result CONFIGURATION. SMTPS and STARTTLS still verify the certificate against the configured host name. APNs push goes only to api.push.apple.com or api.sandbox.push.apple.com; any other host is a configuration error.

These providers power the OTP, magic-link and push delivery used by multi-factor authentication. Configure them per realm so each tenant sends from its own accounts and sender identities.

Templates

Message bodies are templates you author and manage in the console:

  • User-claim passthrough — interpolate any user attribute with {{user.*}} variables (for example {{user.firstName}} or {{user.email}}).
  • HTML email — rich, branded email bodies.
  • Magic-link templating — inject the one-click sign-in link into the message.

Every template can be previewed with sample data and test-sent to a real address or device before you rely on it in production.

42 seconds, no sound. Turn on SMTP email for the realm with example values, save it, look at the SMS and Push providers and preview a message template. Recorded on the current release in a test realm.

In the console

Open Notifications (under Manage). The page has one tab per channel — SMS, Email, Push — and Templates.

  1. On Email, choose the Delivery method (SMTP, Cloudflare Email Service, HTTP relay or Log only), turn it on, fill in the driver's settings and the Sender (From address, From name), optionally a Sending limit, and click Save email settings. A realm sends with one email provider: switching another one on turns the current one off when you save.
  2. On SMS or Push, choose the Provider (Twilio or HTTP gateway; Firebase (FCM) or Apple (APNs)), enter its credentials and click Save provider. Under Send test message, enter a phone number or device token and click Send test.
  3. On Templates, pick a template, edit its Subject and Body, check the Preview, and click Save template.

The Push tab sends the realm's own notification messages. The Authenticator app's sign-in requests use the server-wide route on Push delivery instead (see Device push).

Over the API

Messaging config lives under /admin/realms/{realm}/messaging. The examples below assume you have set $HELIX_URL / $REALM and logged in — see Authenticating to the API.

List providers

A freshly seeded realm has no providers configured — delivery is inert until you add one:

curl -s -b cookies.txt "$HELIX_URL/admin/realms/$REALM/messaging/providers"
[]

Configure a provider

PUT /messaging/providers upserts the whole provider record for a channel/driver. channel and driver are required; the secret is write-only (the read side reports secretSet instead):

# Refresh CSRF after any GET, then PUT (see the auth guide for the helper)
curl -s -b cookies.txt -c cookies.txt "$HELIX_URL/admin/realms/$REALM/messaging/providers" >/dev/null
CSRF=$(awk '($6=="__Host-XSRF-TOKEN"||$6=="XSRF-TOKEN")&&$7~/^r1\./{t=$7} END{print t}' cookies.txt)

curl -s -b cookies.txt -X PUT \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: $CSRF" \
  -d '{
        "channel": "EMAIL",
        "driver": "smtp",
        "enabled": true,
        "fromAddress": "no-reply@acme.example",
        "fromName": "Acme",
        "config": { "host": "smtp.acme.example", "port": 587, "username": "acme" },
        "secret": "smtp-password"
      }' \
  "$HELIX_URL/admin/realms/$REALM/messaging/providers"
{
  "id": "b2f1c0a4-2c1d-4e9a-9f3b-7a10c5d6e8f2",
  "realmId": "acme",
  "channel": "EMAIL",
  "driver": "smtp",
  "enabled": true,
  "fromAddress": "no-reply@acme.example",
  "fromName": "Acme",
  "config": { "host": "smtp.acme.example", "port": 587, "username": "acme" },
  "secretSet": true
}

Send a provider test to confirm delivery (does not persist anything):

curl -s -b cookies.txt -X POST -H "Content-Type: application/json" -H "X-XSRF-TOKEN: $CSRF" \
  -d '{"to":"you@example.com"}' \
  "$HELIX_URL/admin/realms/$REALM/messaging/providers/EMAIL/test"

Manage templates

The realm ships with seeded templates for OTP, magic-link and push. {{…}} placeholders interpolate runtime values and user attributes:

curl -s -b cookies.txt "$HELIX_URL/admin/realms/$REALM/messaging/templates"
[
  { "id": "7d3d015e-7d3c-4277-babd-44966ad861e6", "realmId": "acme", "templateKey": "otp-sms",         "channel": "SMS",   "subject": null,                             "body": "{{realm}} verification code: {{code}} (valid {{ttl}}).", "enabled": true, "html": false },
  { "id": "e99a4b98-641f-4c14-b61c-ef410514b9fa", "realmId": "acme", "templateKey": "otp-email",       "channel": "EMAIL", "subject": "Your {{realm}} verification code","body": "<p>Hi {{user}},</p>…",                                 "enabled": true, "html": true },
  { "id": "8a02ced3-5a8e-4663-aac6-2aa3df73e66c", "realmId": "acme", "templateKey": "magic-link-email","channel": "EMAIL", "subject": "Sign in to {{realm}}",            "body": "<p><a href=\"{{link}}\">Click here…</a></p>",         "enabled": true, "html": true }
]

Edit a template with PUT /messaging/templates, and render a preview without sending:

# Preview a template with sample data (returns the rendered subject/body)
curl -s -b cookies.txt -X POST -H "Content-Type: application/json" -H "X-XSRF-TOKEN: $CSRF" \
  -d '{"templateKey":"otp-email","sample":{"user":"Alice","code":"123456","ttl":"5 minutes"}}' \
  "$HELIX_URL/admin/realms/$REALM/messaging/templates/preview"

Full endpoint set

Method & path (under /admin/realms/{realm}) Purpose
GET /messaging/providers · PUT /messaging/providers List / upsert a channel provider
DELETE /messaging/providers/{channel}/{driver} Remove a provider (console: the provider's Remove, confirmed; the dialog says when it is the provider in use)
POST /messaging/providers/{channel}/test Send a provider delivery test
GET /messaging/templates · PUT /messaging/templates List / edit templates
POST /messaging/templates/preview Render a template without sending

See the API reference.

See also