Skip to main content

Custom Email Templates

Mango allows you to customize the content of email notifications sent by email event handlers using FreeMarker templates. You can include data point values, historical data, event details, and custom formatting to create informative notifications tailored to your operations team.

Prerequisites​

Before creating custom email templates, ensure that outgoing email is configured:

  1. Navigate to Administration > System Settings > Email Settings.
  2. Configure the SMTP host, authentication, and content type.
  3. Send a test email to verify the configuration is working.

For detailed SMTP setup instructions, see Email Settings.

Email settings configuration in Administration > System Settings

Setting Up Event-Triggered Emails​

To send a custom email when an alarm condition occurs, you need three components:

1. Event Detector​

Create an event detector on the data point you want to monitor. For example, to monitor a temperature data point that should not exceed 50 degrees:

  • Navigate to the data point's Event Detectors section.
  • Add a High Limit detector with a limit of 50.
  • Set an appropriate alarm level (e.g., Warning or Urgent).

High Limit event detector configuration for a temperature point

2. Email Event Handler​

Create an email event handler linked to the event detector:

  • Navigate to the Event Handlers page.
  • Create a new handler and choose Email type.
  • Link it to the event detector you created.
  • Add email recipients (mailing lists, specific users, or direct email addresses).
  • Select data points to include as additional context in the email.

Email event handler configuration with recipients and context points

3. Custom Template​

In the Custom Template field of the email event handler, enter your FreeMarker template code. This template overrides the default email body.

FreeMarker Template Basics​

Mango uses FreeMarker as its template engine. FreeMarker provides a powerful syntax for generating dynamic HTML and text content.

Setting a Custom Subject Line​

Use the <@subject> directive to override the default email subject:

<@subject>Alert - Temperature Exceeded Limit</@subject>

Accessing Event Data​

The event object is available as evt in the template model:

<p>Event ID: ${evt.id}</p>
<p>Alarm Level: ${evt.alarmLevel}</p>
<p>Time: ${evt.activeTimestamp?number_to_datetime}</p>

Including Data Point Values​

When you add data points to the email handler's additional context, they become available under additionalContext using the template key you assign to each point. Each context point provides:

  • name -- the data point name
  • deviceName -- the device name
  • values -- a list of rendered point value/timestamp entries

For point events, renderedHtmlPointValues contains the most recent rendered values of the event's source point. This variable is only available for point events when the email content type is set to HTML or both HTML and Text.

Example: Basic Custom Template​

<@subject>Hey - Stuff is happening with the automation system and I think you should know</@subject>
<#if renderedHtmlPointValues??>
  <#list renderedHtmlPointValues as renderedPvt>
  ${additionalContext.temperature.deviceName} - ${additionalContext.temperature.name} - ${renderedPvt.value} - ${renderedPvt.time}<br/>
  </#list>
</#if>

In this example, temperature is the template key assigned to the temperature data point in the event handler's additional context configuration.

Example: Including Point History​

You can use an optional script in the email event handler to add historical data to the model before template rendering. For example, to include the last 10 values of a temperature point:

model.put("temperatureValues", temperature.last(10));

Then in the template:

<h3>Recent Temperature Readings</h3>
<table>
  <tr><th>Value</th><th>Time</th></tr>
  <#list temperatureValues as pv>
    <tr><td>${pv.value}</td><td>${pv.time}</td></tr>
  </#list>
</table>

Available Template Variables​

The following variables are available in email templates:

VariableDescription
evtThe event instance object, providing id, alarmLevel, activeTimestamp, message, context, and more.
pointFor point events, the data point object with name, deviceName, tags, and other properties.
renderedHtmlPointValuesFor point events with HTML content type, an array of the most recent rendered point values.
additionalContextA map of additional context points keyed by the template key you assign in the handler configuration.
modelThe full model map (accessible in scripts to add custom data before template rendering).

Accessing Data Point Tags​

If your data points use tags, you can iterate over them in the template:

<#list point.tags as tag, value>
  ${tag}: ${value}<br/>
</#list>

Event Context by Event Type​

Different event types provide different context data:

  • Data point events: evt.context.dataSource provides the data source object.
  • Data source events: evt.context.dataSource provides the data source object.
  • Publisher events: evt.context.publisher provides the publisher object.
  • Audit events: evt.context provides JSON describing the changes made.
  • System events: evt.context is null.

Advanced: Using Scripts with Templates​

The email event handler supports an optional script that runs before the template is rendered. The script receives the full model map and can modify it, add new entries, or cancel the email entirely.

Script Return Values​

  • Return CANCEL to suppress the email for this event.
  • Return UNCHANGED to send the email with the current model.
  • Any other return value (or no explicit return) sends the email normally.

Example: Conditional Email Suppression​

// Only send email if temperature exceeds 100 (suppress for minor threshold crossings)
if (additionalContext.temperature.value < 100) {
    return "CANCEL";
}
return "UNCHANGED";

Email Content Types​

The content type configured in your Email Settings affects template rendering:

  • HTML and text (default): Mango creates a multi-part MIME email. Your custom template should produce HTML content.
  • HTML only: Single-part HTML email (may become multi-part if there are attachments).
  • Text only: Plain text email. Use plain text in your template rather than HTML tags.

Best Practices​

  • Start with the defaults: The built-in templates at MA_HOME/ftl/ provide good examples. Copy and modify them rather than writing from scratch.
  • Test with low-severity events: Configure a test event detector at the Information level so you can trigger emails without creating false alarms.
  • Use conditional blocks: Wrap optional sections in <#if variable??> checks to prevent errors when variables are not available.
  • Keep templates readable: Use FreeMarker comments (<#-- comment -->) to document complex template logic.
  • Include the <@subject> directive: This gives recipients a clear, actionable subject line rather than the default format.

For complete FreeMarker documentation, see the FreeMarker Manual.