Skip to main content

Email Notification Setup

Email notifications are one of the most important alarm response mechanisms in Mango. They ensure that the right people are informed when events occur, escalate unresolved alarms, and confirm when conditions return to normal. This guide covers the complete email notification setup process, from configuring SMTP settings through building email event handlers with templates and escalation.

Step 1: Configure SMTP Settings​

Before Mango can send any email, you must configure the SMTP (Simple Mail Transfer Protocol) server settings. These settings are used by all emailing activities in the system.

Navigate to System Settings and open the Email section.

Required Settings​

SettingDescription
SMTP hostThe hostname or IP address of your mail server (e.g., smtp.gmail.com, mail.yourcompany.com)
SMTP portThe port number for the SMTP connection. Common values: 25 (unencrypted), 465 (SSL), 587 (STARTTLS)
'From' addressThe email address that will appear as the sender on all Mango emails (e.g., mango@yourcompany.com)

Optional Settings​

SettingDescription
'From' nameA display name or alias for the sender (e.g., "Mango SCADA Alerts")
Use authorizationEnable if your SMTP server requires authentication. Enter the Username and Password for the mail account.
Enable TLSEnable if your server requires Transport Layer Security for encrypted connections
SMTP connection timeoutTimeout in milliseconds for establishing the SMTP connection. A value of 0 means no timeout.
Content typeChoose the email format: HTML and text (default, creates a multi-part MIME email), HTML only, or Text only

Testing Email Delivery​

After configuring SMTP settings, click the Send Test Email button. Mango will attempt to send a test email to the currently logged-in user's email address using the configured settings. Check your inbox (and spam folder) to verify delivery.

If the test email fails:

  • Verify the SMTP host and port are correct and accessible from the Mango server.
  • Check that the username and password are correct if using authentication.
  • Ensure the Mango server's firewall allows outbound connections on the SMTP port.
  • Check the Mango log file (ma.log) for detailed error messages.

Step 2: Create Mailing Lists​

Mailing lists simplify recipient management by grouping multiple email addresses under a single reusable name. Instead of adding individual recipients to every email handler, add a mailing list and manage membership centrally.

Navigate to the Mailing Lists page from the main menu.

Creating a Mailing List​

  1. Click New Mailing List.
  2. Enter a descriptive name (e.g., "Facilities Team", "Night Shift Operators").
  3. Add recipients:
    • Users: Select Mango users by name. Their email addresses are pulled from their user profile and stay in sync if updated.
    • Email addresses: Enter external email addresses for recipients who are not Mango users.
  4. Save the mailing list.

Automatic Alarm Emails​

Each mailing list has a Send alarm emails setting that can be configured to a specific alarm level. When set, the mailing list automatically receives generic alarm notification emails for any event at or above that alarm level during the list's active schedule -- no individual email handler is required. To prevent a mailing list from receiving automatic alarm emails, set this to "Do Not Log" or "Ignore".

Inactive Schedule​

The Inactive schedule section allows you to define time windows when the mailing list should not receive emails. This is useful for shift-based operations where different teams handle alerts at different times.

Step 3: Create Email Event Handlers​

Email event handlers are the core mechanism for sending targeted notifications in response to specific events. Each handler defines who receives the email, what information is included, and how escalation works.

Navigate to the Event Handlers page and create a new handler of type Email.

Basic Configuration​

  1. Handler name: Enter a descriptive name (e.g., "Boiler Room High Temp Alert").
  2. Event types: Select one or more event types that should trigger this handler. You can select specific point event detectors, data source events, system events, or any combination.

Active Notification Recipients​

Add the recipients who should receive the initial notification when the event becomes active:

  • Mailing list: Select a pre-configured mailing list.
  • User: Select an individual Mango user.
  • Email address: Type an email address directly and press Enter to confirm.

Remove any recipient by clicking the X next to their entry.

Subject Line Configuration​

Choose the subject line source:

  • Handler name: Uses the handler's configured name in the subject.
  • Event message: Uses the event's descriptive message in the subject.

The default subject line format is:

{alarmLevel} - {nameOrMessage} ({notificationType}) - id:{eventId}

Where:

  • alarmLevel is the severity (e.g., Urgent, Critical)
  • nameOrMessage is either the handler name or event message
  • notificationType is Active, Escalation, or Inactive
  • eventId is the internal event identifier (not included for Information-level events)

Optional Content​

Enhance the email body with additional context:

  • Include system information: Adds a breakdown of all currently scheduled Work Items by priority. Primarily useful for diagnosing system performance issues.
  • Include point value data: For data point events, includes a specified number of recent point values with timestamps. This provides context about what the point was doing before the alarm triggered.
  • Include log file: Attaches the current Mango log file as a zip archive. Helpful for remote troubleshooting.

Step 4: Configure Escalation​

Escalation ensures that unresolved alarms are not silently ignored. If an event is not resolved or acknowledged within a specified time, Mango sends additional notifications to a separate set of recipients.

Adding Escalation Entries​

Each email handler supports multiple escalation entries. For each entry, configure:

  1. Escalation name (optional): An identifier displayed in the email subject instead of the default notification type.
  2. Escalation delay: The time to wait before sending the first escalation email. This is also the interval between subsequent escalation emails.
  3. Escalation mode:
    • Send until inactive: Continue sending until the event returns to normal.
    • Send until acknowledged: Continue sending until the event is acknowledged or returns to normal.
  4. Maximum emails: Limit the total number of escalation emails sent. Check Send indefinitely to remove the limit.
  5. Recipients: Add the escalation recipients (mailing lists, users, or direct email addresses).

Escalation Example​

A practical escalation setup for a critical temperature alarm:

  • Initial email: Sent to the on-site operator team immediately when the alarm fires.
  • Escalation 1 (15 minutes): If not acknowledged, escalate to the facilities manager.
  • Escalation 2 (30 minutes): If still not acknowledged, escalate to the site director and the external maintenance contractor.

Step 5: Configure Inactive Notification​

Enable Send inactive notification to send a follow-up email when the event returns to normal. This confirms that the condition has been resolved and helps operators close out incidents.

By default, the inactive email is sent to all recipients who received the active or escalation emails. To send the inactive notification to a different set of recipients, check Override inactive recipients and configure a separate recipient list.

Custom FreeMarker Templates​

For advanced email customization, you can provide a custom FreeMarker template that overrides the default email body.

Template Basics​

Default templates are located under MA_HOME/ftl/. The template has access to a model containing:

  • evt: The event object (com.serotonin.m2m2.rt.event.EventInstance), providing access to alarm level, message, timestamps, and context.
  • Additional context points (if configured) under additionalContext, each providing templateKey, name, deviceName, and values.

Template Directives​

DirectivePurpose
<@subject>...</@subject>Set the email subject from within the template
<@fmt message=... />Render translated text using Mango's i18n system
<@fmt key="i18n.key" />Render a specific i18n key

Example: Iterating Point Tags​

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

Example: Conditional Alarm Level Display​

<#if evt.alarmLevel == 4>
  <@fmt key="common.alarmLevel.critical"/>
</#if>

Pre-render Script​

An optional script can modify the email model before the FreeMarker template is rendered. The script receives the entire Map<String, Object> model and can:

  • Modify values in the model.
  • Return CANCEL to prevent the email from being sent.
  • Return UNCHANGED to send the email without modifications.

Script permissions restrict what Mango resources the script can access.

Troubleshooting Email Issues​

ProblemPossible CauseSolution
No emails receivedSMTP settings incorrectVerify host, port, credentials. Use the "Send Test Email" button.
Emails going to spamMissing SPF/DKIM recordsConfigure SPF and DKIM records for the "From" address domain.
Emails delayedEscalation delay too longReview escalation timing. Initial emails should have no delay.
Too many emailsAlarm flappingAdd a duration (e.g., "for at least 30 seconds") to the event detector to prevent rapid on/off cycling.
Template errorsInvalid FreeMarker syntaxCheck the Mango log for template rendering errors. Test with simple templates first.
Authentication failureWrong username/passwordVerify the SMTP credentials. For Gmail, use an App Password if 2FA is enabled.

Best Practices​

  • Always test the SMTP configuration and at least one email handler before deploying to production.
  • Use mailing lists rather than adding individual addresses to every handler. This makes recipient management much easier as personnel change.
  • Set reasonable escalation delays -- too short creates noise, too long delays response.
  • Include point value data in event emails to give recipients immediate context about the alarm condition.
  • Keep custom templates simple and test them thoroughly. A template error can prevent all emails from being sent for that handler.
  • Monitor the Mango log for email delivery errors, especially after SMTP server changes or password rotations.