Mastering Dynamic HTML Email Alerts in Home Assistant: Secure SMTP & Custom Content
NGC 224
DIY Smart Home Creator
Introduction: Elevating Your Home Assistant Notifications with Rich HTML Emails
While Home Assistant offers a plethora of notification options—from app pushes to voice announcements—there are times when a basic text alert simply doesn't cut it. For critical security events, detailed system health reports, or complex automations requiring rich, persistent information, a dynamic HTML email is often the ideal solution. Unlike transient push notifications, emails provide a durable record, can include detailed formatting, images, and multiple data points, making them invaluable for actionable insights and historical review.
This guide dives deep into configuring Home Assistant for secure SMTP-based email notifications, focusing on crafting dynamic HTML content. We'll move beyond simple text, showing you how to embed real-time data, integrate camera snapshots, and ensure your critical alerts are not just delivered, but understood and acted upon.
Step-by-Step Setup: Secure SMTP & Dynamic Content
1. Choosing Your SMTP Service and Configuring Home Assistant
Your first step is to decide on an SMTP service. For maximum control and privacy, especially if you're a DIY enthusiast, a self-hosted mail server like Postfix is excellent. However, for simplicity, cloud SMTP providers like SendGrid, Mailgun, or even a personal Gmail account (with app passwords) are viable.
Here’s how to configure the SMTP notification platform in Home Assistant. We recommend using STARTTLS on port 587 for secure communication.
# configuration.yaml
notify:
- name: smart_home_alerts
platform: smtp
sender: [email protected] # Or your Gmail/SendGrid email
recipient: [email protected]
server: smtp.your-provider.com # e.g., smtp.gmail.com, smtp.sendgrid.net
port: 587 # Often 587 for STARTTLS, or 465 for SSL/TLS
username: your_smtp_username # Your email address for cloud services
password: your_smtp_password # Use an App Password for Gmail
target_email: [email protected] # Can be a list of recipients
tls: True
timeout: 10 # Optional: Increase timeout for slower connections
Replace placeholders with your actual SMTP server details, username, and a Gmail App Password if using Gmail. Restart Home Assistant after making changes.
2. Sending Your First Basic HTML Email
To test your setup, call the `notify.smart_home_alerts` service from Developer Tools -> Services. Set the `message` to some simple HTML.
service: notify.smart_home_alerts
data:
title: "Home Assistant Test Email"
message: "<p>This is a <strong>test</strong> email from Home Assistant.</p><p>If you see this, your SMTP setup is working!</p>"
Check your `[email protected]` inbox. You should receive an email with formatted text.
3. Crafting Dynamic HTML Content with Home Assistant Templates
The real power comes from embedding dynamic data using Home Assistant's Jinja2 templating engine. You can construct the entire HTML body within your automation.
# Example Automation: Door Left Open Alert
alias: "Critical: Front Door Left Open"
description: "Sends a detailed HTML email if front door is open for too long"
trigger:
- platform: state
entity_id: binary_sensor.front_door_contact
to: "on"
for:
minutes: 5
condition:
- condition: state
entity_id: device_tracker.your_phone
state: "not_home" # Only alert if no one is home
action:
- service: notify.smart_home_alerts
data:
title: "🏠 Critical Alert: Front Door Open!"
message: |
<html>
<head><style>body { font-family: sans-serif; } .alert { color: red; font-weight: bold; }</style></head>
<body>
<p>Dear Homeowner,</p>
<p>The <span class="alert">Front Door</span> has been left open for more than 5 minutes.</p>
<p><strong>Status:</strong> {{ states('binary_sensor.front_door_contact') | capitalize }}<br>
<strong>Last Changed:</strong> {{ states.binary_sensor.front_door_contact.last_changed.astimezone(now().tzinfo).strftime('%Y-%m-%d %H:%M:%S %Z') }}<br>
<strong>Temperature Outside:</strong> {{ states('sensor.outside_temperature') }} °C</p>
<p>Please check your security cameras if you are away.</p>
<p><em>This message was automatically generated by Home Assistant.</em></p>
</body>
</html>
mode: single
This automation dynamically pulls the door's state, last changed timestamp, and even outside temperature into a neatly formatted HTML email.
4. Including Attachments (Camera Snapshots)
For security alerts, an image attachment is crucial. You can use the `camera.snapshot` service to save an image and then attach it to your email.
# Example Automation: Motion Detected with Snapshot
alias: "Security: Driveway Motion Detected"
description: "Sends email with snapshot if motion is detected in driveway"
trigger:
- platform: state
entity_id: binary_sensor.driveway_motion
to: "on"
action:
- service: camera.snapshot
data:
entity_id: camera.driveway_camera
filename: /config/www/tmp/driveway_motion_snapshot.jpg # Accessible via HA file system
- delay: 00:00:02 # Give camera time to save snapshot
- service: notify.smart_home_alerts
data:
title: "🚨 Motion Detected: Driveway!"
message: |
<html>
<head><style>body { font-family: sans-serif; } .highlight { color: #007bff; font-weight: bold; }</style></head>
<body>
<p>A <span class="highlight">motion event</span> was detected in the driveway.</p>
<p><strong>Time:</strong> {{ now().astimezone(now().tzinfo).strftime('%Y-%m-%d %H:%M:%S %Z') }}</p>
<p>Please review the attached snapshot.</p>
</body>
</html>
data:
attachments:
- /config/www/tmp/driveway_motion_snapshot.jpg
mode: single
Make sure the `/config/www/tmp/` directory exists and is writable by Home Assistant. The `www` folder is typically accessible publicly (e.g., for `local_file` cameras), so consider your security implications if using it for temporary snapshots. For critical security, you might prefer to store snapshots in a more restricted location and clean them up regularly.
Troubleshooting Section: Common Email Notification Issues
Encountering issues? Don't worry, here are common problems and their solutions:
- Email Not Sending At All:
- Check Home Assistant Logs: Go to "Settings > System > Logs" for specific errors related to the `smtp` platform. Look for "Authentication failed" or "Connection refused."
- Verify SMTP Server Details: Double-check `server`, `port`, `username`, `password`, and `sender` in your `configuration.yaml`. Even a typo can prevent sending.
- Firewall Rules: Ensure your Home Assistant host (or network firewall) allows outbound connections on the specified SMTP port (587 or 465).
- App Passwords: If using Gmail, you MUST use an App Password, not your regular Gmail password.
- HTML Not Rendering Correctly (Plain Text Email):
- Some older email clients or strict corporate email systems might strip HTML. Test with various clients (Gmail, Outlook, Apple Mail).
- Ensure your `message` content is valid HTML. Check for unclosed tags or syntax errors.
- Home Assistant's SMTP integration expects HTML within the `message` field when sending. No special `content_type` is usually needed, it detects HTML automatically.
- Attachments Not Included:
- Verify the file path in `attachments` is correct and accessible by Home Assistant (e.g., `/config/www/tmp/driveway_motion_snapshot.jpg`).
- Ensure the snapshot service successfully saves the file before the email service is called. Add a `delay` if necessary.
- Check Home Assistant logs for errors related to file access or attachment failures.
- Email Being Marked as Spam:
- This can happen if your sender domain isn't properly authenticated (SPF, DKIM records). This is more of an issue with self-hosted SMTP or generic "@gmail.com" senders.
- Using reputable cloud SMTP providers (SendGrid, Mailgun) often helps deliverability.
- Avoid overly "spammy" words in your subject and body, especially for initial tests.
Advanced Configuration and Optimization
1. Rate Limiting and Conditional Sending
To prevent notification fatigue or exceeding your SMTP provider's rate limits, implement conditional logic or rate limiting in your automations.
- Conditions: Only send emails when specific `input_boolean` or `device_tracker` states are met (e.g., `input_boolean.away_mode` is `on`).
- Throttling: Use a `delay` or an `input_datetime` helper to ensure emails for the same event aren't sent more than once every X minutes/hours.
# Example: Throttled Motion Alert
alias: "Throttled Driveway Motion Alert"
trigger:
- platform: state
entity_id: binary_sensor.driveway_motion
to: "on"
condition:
- condition: template
value_template: "{{ (as_timestamp(now()) - as_timestamp(states('input_datetime.last_driveway_alert') | default(0)) | int) > (5 * 60) }}" # 5 minutes throttle
action:
- service: input_datetime.set_datetime
data:
entity_id: input_datetime.last_driveway_alert
datetime: "{{ now().strftime('%Y-%m-%d %H:%M:%S') }}"
- service: camera.snapshot
# ... (as above)
- service: notify.smart_home_alerts
# ... (as above)
Remember to create an `input_datetime.last_driveway_alert` helper.
2. Dynamic Recipient Lists
You can dynamically change the recipient based on conditions, for example, sending alerts to different family members based on who is home or what time it is.
# In your automation action
- service: notify.smart_home_alerts
data_template:
title: "{{ states('sensor.alert_type') }} Detected!"
message: "..."
target_email: >
{% if is_state('device_tracker.johns_phone', 'home') %}
[email protected]
{% elif is_state('device_tracker.janes_phone', 'home') %}
[email protected]
{% else %}
[email protected]
{% endif %}
Note the use of `data_template` instead of `data` when `target_email` itself needs to be templated.
3. Reusable HTML Templates with "Packages" or `!include`
For complex HTML structures, maintainability becomes key. Store your HTML email templates in separate files and `!include` them, or use the Packages feature.
# In your automation action
- service: notify.smart_home_alerts
data:
title: "Alarm Triggered!"
message: !include email_templates/alarm_triggered.html.jinja
Then, `email_templates/alarm_triggered.html.jinja` would contain your full HTML, using Jinja2 variables passed through `message` for context. This approach keeps your automations clean and your HTML manageable.
Real-World Example: Comprehensive HVAC System Alert
Imagine your smart home monitors your HVAC system for optimal performance and efficiency. A critical alert might involve the system running excessively or a sensor reporting an abnormal reading.
# automation.yaml
alias: "HVAC Performance Anomaly Alert"
description: "Sends a detailed HTML email if HVAC runs excessively or reports high humidity"
trigger:
- platform: numeric_state
entity_id: sensor.hvac_run_time_today # Custom sensor tracking daily run time
above: 12 # Hours
- platform: numeric_state
entity_id: sensor.indoor_humidity
above: 65 # Percentage
for:
minutes: 30
condition:
- condition: time
after: "08:00:00"
before: "22:00:00"
action:
- service: notify.smart_home_alerts
data:
title: "🌡️ HVAC Anomaly Detected: Action Required!"
message: |
<html>
<head>
<style>
body { font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; line-height: 1.6; color: #333; }
.container { max-width: 600px; margin: 20px auto; background-color: #f9f9f9; padding: 25px; border-radius: 8px; border: 1px solid #ddd; }
.header { background-color: #dc3545; color: white; padding: 15px; text-align: center; border-radius: 5px 5px 0 0; }
.content { padding: 20px 0; }
.data-point { margin-bottom: 10px; }
.data-label { font-weight: bold; color: #555; display: inline-block; width: 150px; }
.footer { margin-top: 30px; font-size: 0.8em; color: #777; text-align: center; border-top: 1px solid #eee; padding-top: 15px; }
.warning { color: #dc3545; font-weight: bold; }
</style>
</head>
<body>
<div class="container">
<div class="header">
<h2>Home Assistant Critical HVAC Alert</h2>
</div>
<div class="content">
<p>Dear Homeowner,</p>
<p>Your Home Assistant detected an <span class="warning">anomaly in your HVAC system</span> performance.</p>
<div class="data-point"><span class="data-label">Current Time:</span> {{ now().astimezone(now().tzinfo).strftime('%Y-%m-%d %H:%M:%S %Z') }}</div>
<div class="data-point"><span class="data-label">HVAC Run Time Today:</span> <strong>{{ states('sensor.hvac_run_time_today') }} hours</strong> (Threshold: 12h)</div>
<div class="data-point"><span class="data-label">Indoor Temperature:</span> {{ states('sensor.indoor_temperature') }} °C</div>
<div class="data-point"><span class="data-label">Indoor Humidity:</span> <strong>{{ states('sensor.indoor_humidity') }}%</strong> (Threshold: 65%)</div>
<p>Please investigate the system or check for open windows/doors.</p>
</div>
<div class="footer">
<p>This is an automated alert from your Home Assistant Smart Home.</p>
</div>
</div>
</body>
</html>
mode: single
This example demonstrates a well-formatted, informative email with inline CSS for better readability, dynamically pulling multiple sensor values to provide a comprehensive overview of the issue. Such an alert empowers you to quickly diagnose and address potential problems before they escalate.
Best Practices and Wrap-up
Implementing dynamic HTML email alerts significantly enhances your Home Assistant's communication capabilities. To ensure these alerts are reliable, secure, and useful, consider these best practices:
- Security First: Always use dedicated app passwords for services like Gmail. If self-hosting SMTP, ensure it's properly secured with SSL/TLS and strong credentials. Don't embed sensitive information directly in your email body unless absolutely necessary, and consider links to secure dashboards instead.
- Test Thoroughly: Before deploying any critical email automation, test it rigorously under various conditions. Ensure templates render correctly across different email clients.
- Concise & Actionable: While HTML allows for rich content, keep your emails focused. Provide enough information to understand the issue and suggest the next steps, but avoid overwhelming the recipient.
- Fallback Notifications: For truly critical events (e.g., security breaches), consider redundant notification methods (e.g., both email and a push notification) in case one fails.
- Performance: Large attachments can slow down email delivery. Optimize image sizes and consider linking to a locally hosted image if possible, rather than attaching huge files repeatedly.
- Version Control: Store your email templates and automation YAML in a version control system like Git. This helps track changes and simplifies recovery.
By mastering dynamic HTML email alerts, you transform your Home Assistant from a mere automation hub into a proactive, intelligent assistant, keeping you informed with context-rich, actionable insights wherever you are.
NGC 224
Author bio: DIY Smart Home Creator
