UI-first SMTP integration — Configure and manage email notifications entirely through the Home Assistant interface.
The integration domain was renamed from smtp to smtp_email (to avoid colliding with Home Assistant's built-in smtp integration).
If you are upgrading from v1.x, you must migrate:
- Go to Settings > Devices & Services and delete the old SMTP integration entries.
- Delete the old
config/custom_components/smtp/folder (HACS does not remove it automatically on a rename). - Update via HACS, then restart Home Assistant.
- Re-add the integration (config entries do not carry over across the domain change).
- Update your automations/scripts to call
smtp_email.send_messageinstead ofsmtp_email.send_message.
The built-in Home Assistant SMTP notification requires manual YAML configuration. This integration brings full UI support for SMTP setup, making email notifications accessible to everyone:
| Feature | Built-in SMTP | This Integration |
|---|---|---|
| UI Configuration | - | Yes |
| Diagnostic Sensors | - | Yes |
| Service Selector in UI | - | Yes |
- Complete UI Configuration — Set up SMTP accounts through Settings > Devices & Services
- Multiple Email Accounts — Add Gmail, Outlook, Yahoo, and others side by side
- Rich Email Support — Send HTML emails with Jinja2 templates and attachments
- Live Diagnostics — Monitor connection status, errors, and delivery timestamps
- No Restart Required — Add, modify, or remove accounts without restarting HA
- Open HACS > Integrations
- Click ⋮ > Custom repositories
- Add
https://github.com/manjotsc/ha-smtpas Integration - Search for SMTP and install
- Restart Home Assistant
Manual Installation
- Download the
smtp_emailfolder from this repository - Copy to
config/custom_components/ - Restart Home Assistant
custom_components/
└── smtp_email/
├── __init__.py
├── config_flow.py
├── const.py
├── manifest.json
├── notify.py
├── sensor.py
├── services.yaml
├── strings.json
└── translations/
└── en.json
- Go to Settings > Devices & Services
- Click + Add Integration
- Search for SMTP
- Enter your email server details
| Option | Description |
|---|---|
| Mail server | SMTP server address (e.g., smtp.gmail.com) |
| Port | 587 (STARTTLS), 465 (SSL/TLS), or 25 (none) |
| Security | STARTTLS (recommended), SSL/TLS, or None |
| Login | Your email username |
| Password | Email password or app-specific password |
| From address | Sender email address |
| From name | Display name shown to recipients |
| To address | Default recipient(s), comma-separated |
| Connection timeout | Seconds to wait for server response |
| Verify SSL | Certificate validation (keep enabled) |
| Debug logging | Log SMTP traffic for troubleshooting |
Common Provider Settings
| Provider | Server | Port | Security |
|---|---|---|---|
| Gmail | smtp.gmail.com |
587 | STARTTLS |
| Outlook/365 | smtp.office365.com |
587 | STARTTLS |
| Yahoo | smtp.mail.yahoo.com |
587 | STARTTLS |
| iCloud | smtp.mail.me.com |
587 | STARTTLS |
Note: Gmail, Outlook, and other providers require an App Password when 2FA is enabled. Generate one in your account security settings.
Use the smtp_email.send_message service to send emails from automations, scripts, or the developer tools.
Basic Example:
service: smtp_email.send_message
data:
config_entry: abc123def456
subject: "Home Assistant Alert"
message: "Motion detected in the living room!"With Templates:
service: smtp_email.send_message
data:
config_entry: abc123def456
subject: "Daily Report"
message: |
Current temperature: {{ states('sensor.temperature') }}°C
Humidity: {{ states('sensor.humidity') }}%HTML Email Example
service: smtp_email.send_message
data:
config_entry: abc123def456
subject: "Home Assistant Status"
message: "Plain text fallback"
html: |
<!doctype html>
<html>
<body style="font-family: Arial, sans-serif; padding: 20px;">
<h1>Home Assistant Status</h1>
<p><strong>Installed:</strong> {{ state_attr('update.home_assistant_core_update', 'installed_version') }}</p>
<p><strong>Latest:</strong> {{ state_attr('update.home_assistant_core_update', 'latest_version') }}</p>
</body>
</html>Multiple Recipients
service: smtp_email.send_message
data:
config_entry: abc123def456
subject: "Alert"
message: "This goes to multiple people"
to:
- "person1@example.com"
- "person2@example.com"With Attachments
service: smtp_email.send_message
data:
config_entry: abc123def456
subject: "Camera Snapshot"
message: "See attached image"
images:
- "/config/www/camera_snapshot.jpg"| Parameter | Required | Description |
|---|---|---|
config_entry |
Yes | SMTP account to use (selectable in UI) |
message |
* | Plain text body (supports templates) |
subject |
No | Email subject line |
to |
No | Recipients list (defaults to configured address) |
from_name |
No | Override sender display name |
html |
* | HTML content (supports templates) |
images |
No | List of image paths to attach |
*At least one of message or html should be provided.
Each SMTP account creates diagnostic entities to monitor email delivery:
| Sensor | Description |
|---|---|
| Status | Connected, Sending, or Error |
| Last Error | Most recent error message |
| Last Sent | Timestamp of last successful delivery |
Daily Morning Report
automation:
- alias: "Daily Status Email"
trigger:
- platform: time
at: "08:00:00"
action:
- service: smtp_email.send_message
data:
config_entry: abc123def456
subject: "Good Morning Report"
message: |
Temperature: {{ states('sensor.temperature') }}°C
Humidity: {{ states('sensor.humidity') }}%
Weather: {{ states('weather.home') }}Motion Detection Alert
automation:
- alias: "Motion Alert Email"
trigger:
- platform: state
entity_id: binary_sensor.front_door_motion
to: "on"
action:
- service: smtp_email.send_message
data:
config_entry: abc123def456
subject: "Motion Detected!"
message: "Motion at front door — {{ now().strftime('%H:%M:%S') }}"Connection Issues
- Verify server address and port
- Check if your provider requires an app password
- Try switching between STARTTLS and SSL/TLS
- Enable debug logging to inspect SMTP traffic
Authentication Errors
- Gmail: Generate an App Password
- Outlook: Create an App Password
- Ensure 2FA is enabled before generating app passwords
Emails Not Arriving
- Check spam/junk folder
- Verify recipient address
- Check the Last Error sensor
- Review Home Assistant logs
Contributions are welcome! Please open an issue or submit a pull request.
This project is licensed under the MIT License.