Configuring Event Handlers and Email Alerts

Overview

Mango by Radix IoT’s event system monitors points for conditions such as high temperature or lost communication and can respond by sending email alerts. This guide covers the complete path from SMTP configuration through event detectors, email handlers, escalation, testing, and custom FreeMarker templates.

Prerequisites

• A running Mango 4.x or 5.x instance
• Administrator access to system email settings
• A working SMTP account
• A data point to monitor
• Email addresses for alarm recipients

Step 1: Configure the Email Sender

Go to Administration > System settings > Email settings and enter the SMTP details.

Click Send test email to verify the configuration. It goes to the address on your own user profile, not to a recipient you choose.

Step 2: Create an Event Detector

1. Open the data point to monitor.
2. Select Event detectors.
3. Click +.
4. Choose a detector type and configure its condition.

For example, a high-temperature detector could use:

• Type: High limit
• Limit: 85
• Duration: 30 seconds
• Alarm level: Urgent

The duration prevents a brief spike from immediately raising an alarm.

Step 3: Create an Email Event Handler

1. Go to Event Management > Event handlers.
2. Click +.
3. Select the Email handler type.
4. Link the handler to the event detector.

Recipients

Add the addresses that should receive active-alarm notifications. You can also add escalation recipients who are notified if the event is not acknowledged within the configured delay.

Escalation adds recipients and notifications over time. It does not limit notification frequency.

Email Content

• Subject: Choose whether the normal subject uses the handler name or event message. A custom template can override it.
• Body: Use the built-in content or supply a custom FreeMarker template.
• Include previous point values for point events: include recent readings for immediate context.

Step 4: Test the Setup

1. Set the point to a value that triggers the detector, if it is safe to do so.
2. Otherwise, wait for a real event.
3. Confirm the event appears on the Events page, filtered to the right event type.
4. Confirm the email reaches the intended recipients.

Customizing Email Content

Custom email templates use FreeMarker syntax. Variables use ${...}, directives use <#...>, and Mango macros use <@...>. Double-curly-brace syntax such as {{evt.message}} is not valid for these templates.

Custom Subject

Inside a custom template, <@subject> overrides the handler’s normal Subject setting. It can accept message=, key=, or value=, or contain body content between opening and closing tags.

This example customizes both subject and body:

<@subject><@fmt message=evt.alarmLevel.description/> ALARM: <@fmt message=evt.message/></@subject>

<@fmt message=evt.message/>

Triggered: ${evt.activeTimestamp?number_to_datetime?string["yyyy/MM/dd HH:mm:ss"]}
<#if evt.rtnTimestamp??>
Returned to normal: ${evt.rtnTimestamp?number_to_datetime?string["yyyy/MM/dd HH:mm:ss"]}
</#if>

<#if renderedPointValues??>
Recent values:
<#list renderedPointValues as renderedPvt>
${renderedPvt.value} @ ${renderedPvt.time}
</#list>
</#if>

This is an automated message from Mango.

For an urgent high-limit event, the rendered message might resemble:

Subject: Urgent ALARM: RTU-01 Temperature has exceeded 85.0°F for more than 30 seconds

RTU-01 Temperature has exceeded 85.0°F for more than 30 seconds

Triggered: 2026/08/21 14:32:07

Recent values:
81.4°F @ 2026/08/21 14:31:07
83.9°F @ 2026/08/21 14:31:22
86.2°F @ 2026/08/21 14:31:37
89.7°F @ 2026/08/21 14:31:52
92.3°F @ 2026/08/21 14:32:07

This is an automated message from Mango.

The return-to-normal line is absent while the event is active because evt.rtnTimestamp is null. The <#if evt.rtnTimestamp??> guard prevents the template from trying to format a missing timestamp.

Verification

• Send test email succeeds.
• The detector raises an event after its configured duration.
• Active-alarm recipients receive the message.
• Escalation recipients are added only after the escalation delay.
• Custom templates render ${...} expressions and the <@subject> directive correctly.
• Return-to-normal content appears only after the event returns to normal.

Troubleshooting

Emails Are Not Sending

• Review Administration > System settings > Email settings.
• Use Send test email.
• Check ma.log for SMTP errors.
• Confirm outbound firewall access to the SMTP port.

Too Many Emails

• Add a duration to the detector to filter short-lived noise.
• Review escalation entries. Each escalation can add recipients and messages after a delay, increasing volume.
• Establish an alarm acknowledgment workflow.

Detector Does Not Trigger

• Verify the threshold and duration.
• Confirm the point is receiving values.
• Check the detector’s Alarm level. There is no “None” option — the lowest ordinary level displays as Minor, and it does raise events. The two that stop an email are Do not log and Ignore, which sit below Minor in the list.

Template Fails to Render

• Use FreeMarker ${...}, not {{...}}.
• Use <@fmt message=.../> for translatable messages.
• Guard evt.rtnTimestamp with <#if evt.rtnTimestamp??>.
• Use <@subject>...</@subject> inside the custom template to override the subject.

Related Guides

• How to Configure Event Handlers: Email, Scripts, Set Points, and Process
• Guide to Event Detector Types in Mango