Skip to content

Email Route Implementation in Coreflux MQTT Broker

Feature Since Version Notes
Email Route >v1.6.2 Enables sending email notifications from MQTT events.

Overview

The Email Route implementation in the Coreflux MQTT broker enables sending email notifications triggered by MQTT events. This powerful feature allows you to set up automated email alerts, notifications, and reports based on data flowing through your IoT system.

For practical examples of LOT Routes, check out the Routes examples in the LOT Samples Repository.

Syntax

The basic syntax for defining an Email Route is:

DEFINE ROUTE EmailRouteName AS EMAIL
WITH SERVER "smtp.example.com"
WITH PORT 587
WITH USERNAME "your_email@example.com"
WITH PASSWORD "your_password"
WITH FROM "your_email@example.com"
WITH TLS TRUE
WITH TRIGGER "topic/to/monitor"
WITH RECIPIENTS "recipient1@example.com, recipient2@example.com"
WITH SUBJECT "Alert: {payload.event_type}"
WITH BODY """
Dear Admin,

An important event has occurred:
Event: {payload.event_type}
Device: {payload.device_id}
Time: {payload.timestamp}
Value: {payload.value}

Please check the system.

Regards,
Coreflux Monitoring System
"""

Key Parameters

Parameter Description Required
SERVER SMTP server address Yes
PORT SMTP server port (usually 587 for TLS, 465 for SSL, or 25) Yes
USERNAME Email account username Yes
PASSWORD Email account password Yes
FROM Sender email address Yes
TLS Whether to use TLS encryption (TRUE/FALSE) Yes
TRIGGER MQTT topic that will trigger the email Yes
RECIPIENTS Comma-separated list of email recipients Yes
SUBJECT Email subject line (supports variables from payload) Yes
BODY Email body content (supports variables from payload) Yes

Variable Substitution

Both the SUBJECT and BODY parameters support variable substitution using payload data. Use curly braces to reference JSON payload values:

  • {payload.property} - Access a property from the JSON payload
  • {payload.nested.property} - Access nested properties
  • {topic} - The full topic that triggered the email
  • {topic[n]} - Access specific segments of the topic (0-based index)

Example: Temperature Alert

DEFINE ROUTE TemperatureAlert AS EMAIL
WITH SERVER "smtp.gmail.com"
WITH PORT 587
WITH USERNAME "iot.monitor@example.com"
WITH PASSWORD "app_password_here"
WITH FROM "iot.monitor@example.com"
WITH TLS TRUE
WITH TRIGGER "sensors/temperature/+/hightemp"
WITH RECIPIENTS "admin@example.com, operations@example.com"
WITH SUBJECT "ALERT: High Temperature Detected in {topic[2]}"
WITH BODY """
<html>
<body>
<h2>Temperature Alert</h2>
<p>A high temperature reading has been detected:</p>
<ul>
  <li><strong>Location:</strong> {topic[2]}</li>
  <li><strong>Temperature:</strong> {payload.temperature}°C</li>
  <li><strong>Timestamp:</strong> {payload.timestamp}</li>
  <li><strong>Device ID:</strong> {payload.device_id}</li>
</ul>
<p>Please take appropriate action if this temperature exceeds safe operating conditions.</p>
</body>
</html>
"""

In this example, when a temperature sensor publishes to a topic like sensors/temperature/server-room/hightemp, an email alert will be sent with the location extracted from the topic and details from the payload.

Adding the Route via MQTT Command

To deploy this route to the broker, use the -addRoute command by publishing to the $SYS/Coreflux/Command topic:

-addRoute DEFINE ROUTE TemperatureAlert AS EMAIL
WITH SERVER "smtp.gmail.com"
WITH PORT 587
WITH USERNAME "iot.monitor@example.com"
WITH PASSWORD "app_password_here"
WITH FROM "iot.monitor@example.com"
WITH TLS TRUE
WITH TRIGGER "sensors/temperature/+/hightemp"
WITH RECIPIENTS "admin@example.com, operations@example.com"
WITH SUBJECT "ALERT: High Temperature Detected in {topic[2]}"
WITH BODY """
<html>
<body>
<h2>Temperature Alert</h2>
<p>A high temperature reading has been detected:</p>
<ul>
  <li><strong>Location:</strong> {topic[2]}</li>
  <li><strong>Temperature:</strong> {payload.temperature}°C</li>
  <li><strong>Timestamp:</strong> {payload.timestamp}</li>
  <li><strong>Device ID:</strong> {payload.device_id}</li>
</ul>
<p>Please take appropriate action if this temperature exceeds safe operating conditions.</p>
</body>
</html>
"""

For more information about broker commands, see the MQTT Broker Commands documentation.

Deploying Routes with LOT Notebooks

Routes can also be created and deployed interactively using LOT Notebooks in Visual Studio Code. This provides a convenient way to develop, test, and document your routes.

To get started with LOT Notebooks: 1. Install the LOT Notebooks extension in VS Code 2. Create a new .lotnb file 3. Add code cells with your route definitions (without the -addRoute prefix) 4. Execute the cells to deploy directly to your broker

For detailed instructions, see the LOT Notebooks Getting Started Guide.

HTML Email Support

The BODY parameter supports HTML formatting for rich email content. Use triple quotes (""") to define multi-line body content with HTML tags.

Security Considerations

  • Store credentials securely and use app-specific passwords when supported
  • Consider using environment variables or secrets management for passwords
  • Use TLS encryption whenever possible
  • Restrict the permissions of the email account used for sending
  • Be cautious with the information included in email bodies to prevent data leakage

Implementation Notes

  1. The Email Route requires a valid SMTP server and credentials
  2. Test your email setup with non-critical notifications first
  3. Add appropriate error handling in your system for failed email deliveries
  4. Consider rate limiting to prevent excessive emails during event storms

The Email Route in Coreflux MQTT Broker provides a direct way to bridge your IoT system with email notifications, enabling timely alerts and reports based on your IoT data.