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 <route_name> WITH TYPE EMAIL
    ADD MQTT_CONFIG
        WITH BROKER_ADDRESS "<broker_address>"
        WITH BROKER_PORT '<port>'
        WITH CLIENT_ID "<client_id>"
        WITH USERNAME "<username>"
        WITH PASSWORD "<password>"
        WITH USE_TLS <true|false>
    ADD SMTP_CONFIG
        WITH HOST "<smtp_server>"
        WITH PORT '<smtp_port>'
        WITH USERNAME "<email_account>"
        WITH PASSWORD "<email_password>"
        WITH USE_TLS <true|false>
    ADD MAPPING <mapping_name>
        WITH SOURCE_TOPIC "<topic>"
        WITH TEMPLATE_PATH "<path_to_html_template>"
        WITH SUBJECT "<subject_template>"
        WITH RECIPIENT "<recipient_template>"

Configuration Parameters

MQTT Configuration (MQTT_CONFIG)

  • BROKER_ADDRESS: Address of the MQTT broker
  • BROKER_PORT: MQTT broker port (default: 1883)
  • CLIENT_ID: Unique identifier for the MQTT client
  • USERNAME and PASSWORD: Credentials for authentication (optional)
  • USE_TLS: Enable secure communication via TLS

SMTP Configuration (SMTP_CONFIG)

  • HOST: SMTP server address (e.g., smtp.gmail.com)
  • PORT: SMTP server port (e.g., 587 for TLS, 465 for SSL)
  • USERNAME: Email account to send from
  • PASSWORD: App password or account password
  • USE_TLS: Enable secure email sending (recommended: true)

Mapping Parameters

  • SOURCE_TOPIC: MQTT topic that triggers the email
  • TEMPLATE_PATH: Path to the HTML file used as the email body
  • SUBJECT: Email subject. Can use placeholders (see below)
  • RECIPIENT: Target email address. Can also use placeholders from the payload

Placeholder Syntax

Email templates (both subject and body) support dynamic rendering from the MQTT message payload:

  • {value}: Full JSON payload string
  • {value.json.key}: Inject a single value from the JSON
  • {value.json.key.subkey}: Support for nested values

Example: Basic Email Route

DEFINE ROUTE TempAlert WITH TYPE EMAIL
    ADD MQTT_CONFIG
        WITH BROKER_ADDRESS "127.0.0.1"
        WITH BROKER_PORT '1883'
        WITH CLIENT_ID "EmailNotifier"
    ADD SMTP_CONFIG
        WITH HOST "smtp.gmail.com"
        WITH PORT '587'
        WITH USERNAME "alerts@mycompany.com"
        WITH PASSWORD "my-app-password"
        WITH USE_TLS true
    ADD MAPPING tempWarning
        WITH SOURCE_TOPIC "sensors/+/warning"
        WITH TEMPLATE_PATH "/templates/warning.html"
        WITH SUBJECT "Sensor Warning: {value.json.device}"
        WITH RECIPIENT "team@mycompany.com"

In this example, when any sensor publishes to a topic like sensors/sensor1/warning, an email will be sent using the HTML template with dynamic content 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 TempAlert WITH TYPE EMAIL
    ADD MQTT_CONFIG
        WITH BROKER_ADDRESS "127.0.0.1"
        WITH BROKER_PORT '1883'
        WITH CLIENT_ID "EmailNotifier"
    ADD SMTP_CONFIG
        WITH HOST "smtp.gmail.com"
        WITH PORT '587'
        WITH USERNAME "alerts@mycompany.com"
        WITH PASSWORD "my-app-password"
        WITH USE_TLS true
    ADD MAPPING tempWarning
        WITH SOURCE_TOPIC "sensors/+/warning"
        WITH TEMPLATE_PATH "/templates/warning.html"
        WITH SUBJECT "Sensor Warning: {value.json.device}"
        WITH RECIPIENT "team@mycompany.com"

Example HTML Template

Create a file at /templates/warning.html:

<!DOCTYPE html>
<html>
<body>
    <h2>Sensor Warning Alert</h2>
    <p>A warning has been detected from sensor: <strong>{value.json.device}</strong></p>
    <p><b>Temperature:</b> {value.json.status.temp}</p>
    <p><b>Humidity:</b> {value.json.status.humidity}</p>
    <p>Please investigate immediately.</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.