> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Email Route

> Send templated email notifications and alerts from MQTT messages over SMTP

## Email Overview

The `EMAIL` route sends templated emails in response to MQTT messages. It's the simplest way to turn a broker event — a critical alarm, a daily report, a user notification — into a message that reaches a person's inbox.

<Tip>
  **Like an auto-reply rule in your mailbox.** When a message lands on a topic you're watching, the route fills in a template and sends the email for you — no manual step required.
</Tip>

### When to use it

* Alert an operations team the moment a critical alarm fires.
* Email a stakeholder a daily or shift report.
* Notify an individual user using an address pulled from the message payload.

***

Let's look at how to define an email route, starting with the most common scenarios.

## Quick Start

<Tabs>
  <Tab title="Critical alert">
    Send an immediate alert to a fixed team address when a critical event arrives:

    ```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    DEFINE ROUTE CriticalAlerts WITH TYPE EMAIL
        ADD SMTP_CONFIG
            WITH HOST "smtp.gmail.com"
            WITH PORT '587'
            WITH USERNAME "alerts@company.com"
            WITH PASSWORD "app-password-here"
            WITH USE_TLS "true"
        ADD EVENT criticalNotify
            WITH SOURCE_TOPIC "alerts/critical/+"
            WITH TEMPLATE_PATH "/templates/critical_alert.html"
            WITH SUBJECT "CRITICAL: {value.json.alert_type}"
            WITH RECIPIENT "ops-team@company.com"
    ```
  </Tab>

  <Tab title="Dynamic recipient">
    Send to an address taken from the message payload:

    ```lot wrap  theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    DEFINE ROUTE UserNotifications WITH TYPE EMAIL
        ADD SMTP_CONFIG
            WITH HOST "smtp.office365.com"
            WITH PORT '587'
            WITH USERNAME "noreply@company.com"
            WITH PASSWORD "secure-password"
            WITH USE_TLS "true"
        ADD EVENT userNotify
            WITH SOURCE_TOPIC "users/+/notifications"
            WITH TEMPLATE_PATH "/templates/user_notification.html"
            WITH SUBJECT "Hello {value.json.username}"
            WITH RECIPIENT "{value.json.email}"
    ```
  </Tab>

  <Tab title="Report with images">
    Embed images (a logo, a chart) directly in the email:

    ```lot wrap  theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    DEFINE ROUTE ReportEmail WITH TYPE EMAIL
        ADD SMTP_CONFIG
            WITH HOST "smtp.company.com"
            WITH PORT '587'
            WITH USERNAME "reports@company.com"
            WITH PASSWORD "password"
            WITH USE_TLS "true"
        ADD EVENT sendReport
            WITH SOURCE_TOPIC "reports/daily"
            WITH TEMPLATE_PATH "/templates/daily_report.html"
            WITH SUBJECT "Daily Report - {value.json.date}"
            WITH RECIPIENT "management@company.com"
            WITH EMBED_RESOURCES
                ADD "/images/logo.png"
                ADD "/images/chart.png"
    ```
  </Tab>
</Tabs>

<Note>
  For Gmail, use an [App Password](https://support.google.com/accounts/answer/185833) instead of your regular password. Enable 2FA on your Google account first.
</Note>

***

## SMTP Configuration

The `SMTP_CONFIG` block tells the route which mail server to send through and how to authenticate.

<AccordionGroup>
  <Accordion title="Server Settings">
    <ParamField path="HOST" type="string" required>
      SMTP server address (e.g., `smtp.gmail.com`, `smtp.office365.com`).
    </ParamField>

    <ParamField path="PORT" type="integer" required>
      SMTP port (typically 587 for TLS, 465 for SSL).
    </ParamField>

    <ParamField path="USE_TLS" type="boolean">
      Enable TLS encryption. Recommended: true.
    </ParamField>
  </Accordion>

  <Accordion title="Authentication">
    <ParamField path="USERNAME" type="string" required>
      Email account to send from.
    </ParamField>

    <ParamField path="PASSWORD" type="string" required>
      Email password or app-specific password.
    </ParamField>
  </Accordion>
</AccordionGroup>

***

## Event Configuration

Each `ADD EVENT` block defines a trigger topic and the content of the email it sends.

<AccordionGroup>
  <Accordion title="Trigger & Routing">
    <ParamField path="SOURCE_TOPIC" type="string">
      MQTT topic to trigger email sending.
    </ParamField>

    <ParamField path="DESTINATION_TOPIC" type="string">
      MQTT topic to publish send status.
    </ParamField>
  </Accordion>

  <Accordion title="Email Content">
    <ParamField path="TEMPLATE_PATH" type="string">
      Path to HTML email template file.
    </ParamField>

    <ParamField path="SUBJECT" type="string">
      Email subject line (supports placeholders).
    </ParamField>

    <ParamField path="RECIPIENT" type="string">
      Email recipient address (supports placeholders).
    </ParamField>
  </Accordion>
</AccordionGroup>

### Template Placeholders

Subjects, recipients, and templates support placeholders that are filled in from the triggering message:

| Placeholder                 | Description                 |
| --------------------------- | --------------------------- |
| `{value}`                   | Full JSON payload as string |
| `{value.json.field}`        | Single field from JSON      |
| `{value.json.nested.field}` | Nested field access         |

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Email Not Sending">
    * Verify SMTP credentials are correct
    * For Gmail, ensure you're using an App Password
    * Check firewall allows outbound SMTP connections
    * Verify recipient email address is valid
  </Accordion>

  <Accordion title="Email Authentication Failed">
    * Double-check USERNAME and PASSWORD
    * Ensure 2FA is enabled if using app passwords
    * Some providers require enabling "less secure apps" access
    * Check for account lockouts due to failed attempts
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="MQTT Bridge" icon="arrow-right-arrow-left" href="./mqtt-bridge">
    Sync topics between two MQTT brokers.
  </Card>

  <Card title="Data Storage Routes" icon="database" href="../data-storage/overview">
    Store MQTT data in databases.
  </Card>
</CardGroup>