Configuring Email and SMTP Settings

Overview

Mango by Radix IoT uses outbound email for alarm notifications, event handlers, scheduled reports, and password-reset links. These features require a valid SMTP connection. This guide covers UI and properties-file configuration, common providers, testing, event handlers, and delivery troubleshooting.

Prerequisites

• A running Mango 4.x or 5.x instance with administrator access
• An SMTP server or email service account
• Network access from Mango to the SMTP host and port
• Two-factor authentication enabled if using a Gmail App Password
• A valid email address on the administrator account used for testing

Step 1: Open Email System Settings

The most common method is the UI:

1. Log in as an administrator.
2. Go to Administration > System settings.
3. Select Email settings.

For headless or automated setups, use a properties file. There is no --config command-line flag. An explicit path comes from the mango.config Java system property, or the mango_config or MA_ENV_PROPERTIES environment variables. With none of those set, Mango takes the first file that exists from <data directory>/mango.properties (the recommended location), <data directory>/env.properties, ~/mango.properties, and two legacy paths under the installation directory. Only one file is ever read, so a second one sitting beside it is silently ignored.

Values resolve in this order, highest first: Java system properties (-Dmango.<key>), environment variables (mango_<key>, underscores in place of dots), your config file, then Mango’s built-in defaults on the classpath. Your config file is optional; nothing creates it for you.

Add overrides as systemSettings.<key>=<value>. Mango watches the configuration file and hot-reloads changes after it is saved, so no restart is required — that watcher is on unless you set properties.reloading=false.

Step 2: Configure SMTP

Related overrides include systemSettings.emailSendTimeout, systemSettings.emailContentType, and systemSettings.emailDisabled. The last setting suppresses all outbound email without removing the connection configuration, and it is the same Disable sending emails checkbox that sits at the top of the Email settings page — while it is on, every other field on that page is hidden.

Example <data directory>/mango.properties:

systemSettings.emailSmtpHost=smtp.yourserver.com
systemSettings.emailSmtpPort=587
systemSettings.emailFromAddress=mango-alerts@yourcompany.com
systemSettings.emailFromName=Mango Automation
systemSettings.emailAuthorization=true
systemSettings.emailSmtpUsername=mango-alerts@yourcompany.com
systemSettings.emailSmtpPassword=your-password-here
systemSettings.emailTls=true

Step 3: Configure Gmail

1. Enable two-factor authentication under Google Account > Security.
2. Generate an App Password under Security > App Passwords.
3. Copy the generated password.
4. Enter these settings:

Step 4: Configure SendGrid

1. Create a SendGrid API key with Mail Send permission.
2. Copy the key when it is displayed.
3. Enter:

Step 5: Configure Microsoft 365

Step 6: Test Email Delivery

1. Go to Administration > System settings > Email settings.
2. Click Send test email.
3. Check the inbox and spam folder for the logged-in user’s email address.
4. If the test fails, review the displayed SMTP session log and ma.log.

Test network connectivity independently with:

openssl s_client -connect smtp.gmail.com:587 -starttls smtp

If the connection opens and displays a certificate, the Mango server can reach the SMTP endpoint.

Step 7: Use Email Event Handlers

After SMTP works:

1. Go to Event Management > Event handlers and add a handler of type Email.
2. Select the events that trigger it.
3. Fill in Email recipients, and if you need them, the Escalation and Inactive email sections.
4. Set Subject line to Include handler name or Include event message.
5. Optionally enable Include system information, Include logfile, and Include previous point values for point events.

That point-value count defaults to 10. As its label says, it only applies when the triggering event belongs to a data point; system and data-source events have no associated point history.

For full control, configure an advanced custom FreeMarker template. It uses syntax such as:

${evt.message}
${evt.activeTimestamp?number_to_datetime?string["yyyy/MM/dd HH:mm:ss"]}

Verification

• Send test email reaches the logged-in user’s address.
• Saving <data directory>/mango.properties updates the settings without a restart, and ma.log records “Mango properties file reloaded”.
• ma.log contains no recurring SMTP errors.
• An email event handler delivers a test alarm.
• “From” address and “From” name display correctly.

Troubleshooting

TLS Handshake Failed

• Match port and TLS mode: port 587 normally uses STARTTLS with systemSettings.emailTls=true; port 465 uses implicit SSL.
• Update the Java trust store when certificate authorities are missing.
• Import a corporate proxy’s CA certificate if SSL inspection is in use.

Authentication Failed

• Recheck the username and password.
• For Gmail, use an App Password.
• For SendGrid, use apikey as the username.
• For Microsoft 365, confirm SMTP AUTH is enabled.

Connection Timed Out

• Test connectivity from the Mango server.
• Review outbound firewall rules.
• Check cloud-provider restrictions on SMTP ports.
• Configure Java proxy settings when required.

Messages Go to Spam

• Configure SPF, DKIM, and DMARC.
• Use a sender address on the authenticated domain.
• Use a transactional email provider for production delivery.

Relay Access Denied

• Confirm the sender is authorized by the SMTP provider.
• For Gmail, use the authenticated account or a configured alias.
• For SendGrid, use a verified sender identity.

Related Guides

• Configuring Event Handlers and Email Alerts
• Configuring Slack Notifications for Mango Alarms
• Creating Excel Reports with Scheduled Email Delivery