homebridge-icloud-smtp

Homebridge dynamic platform plugin that creates virtual HomeKit switches that send emails through iCloud SMTP when triggered.

Features

• Send emails using iCloud SMTP
• Trigger emails using HomeKit switches
• Supports per-switch recipients
• Uses Apple app-specific password
• Lightweight with minimal dependencies
• Compatible with Homebridge v2

Example Use Cases

• Send yourself a notification when a HomeKit automation runs
• Trigger email alerts from sensors or switches
• Create simple notification workflows inside Apple Home

Requirements

• Homebridge ^1.8.0 || ^2.0.0
• Node.js ^22.10.0 || ^24.0.0
• iCloud account
• Apple app-specific password

Installation

Install from npm:

sudo npm install -g homebridge-icloud-smtp

Or install through the Homebridge UI:

1. Open Homebridge UI
2. Go to Plugins
3. Search for homebridge-icloud-smtp
4. Install the plugin

Configuration

Example configuration:

{
	"platform": "ICloudSMTP",
	"name": "iCloud SMTP",
	"username": "[email protected]",
	"password": "your-app-specific-password",
	"switches": [
		{
			"id": "door-alert",
			"name": "Door Alert",
			"to": "[email protected],[email protected]",
			"subject": "Door Opened",
			"body": "The front door was opened.",
			"cooldown": 30
		},
		{
			"id": "window-left-open",
			"name": "Window left open",
			"subject": "A window is left open",
			"cooldown": 600
		}
	]
}

Option Reference

Platform Options

| Option | Type | Required | Description | |---|---|---|---| | platform | string | Yes | Must be ICloudSMTP | | name | string | No | Display name in Homebridge | | username | string | Yes | iCloud email address used as sender | | password | string | Yes | Apple app-specific password | | switches | array | Yes | List of virtual HomeKit switches |

Switch Options

| Option | Type | Required | Description | |---|---|---|---| | id | string | Yes | Unique, stable accessory identifier. Renaming the explicit id will create a new accessory in HomeKit (losing room assignments and automations) | | name | string | Yes | Switch name shown in HomeKit | | subject | string | Yes | Email subject | | body | string | No | Plain text email body | | to | string | No | Recipient email address(es). Multiple recipients supported via comma-separated values | | cooldown | number | No | Minimum seconds between sends (default: 30) |

Recipient Behavior

• If to is omitted, the email is automatically sent to the configured username
• Multiple recipients are supported using comma-separated email addresses

Example:

"to": "[email protected],[email protected]"

Apple App-Specific Password

Apple requires app-specific passwords for SMTP access from third-party applications.

Steps:

1. Sign in at https://account.apple.com
2. Open Sign-In and Security
3. Select App-Specific Passwords
4. Generate a new app-specific password
5. Use the generated password in the plugin configuration

Apple Support reference:

https://support.apple.com/en-us/102654

How It Works

• The plugin registers a dynamic Homebridge platform (ICloudSMTP)
• Each configured switch appears as a HomeKit switch
• Turning a switch on sends an email
• The switch automatically resets to off after triggering
• Emails are sent using Nodemailer with the built-in iCloud SMTP service configuration

Troubleshooting

Authentication failed

• Ensure you are using an Apple app-specific password
• Do not use your Apple account password
• Regenerate the app-specific password if needed

No email received

• Check Homebridge logs for SMTP errors
• Verify recipient addresses
• Check spam/junk folders
• Ensure cooldown timing is not blocking repeated sends

Plugin does not start

• Verify username and password are configured
• Ensure at least one switch exists in switches

Security Recommendations

• Use an Apple app-specific password
• Never share your Homebridge config.json publicly
• Consider using a dedicated secondary iCloud account
• Revoke the app-specific password if no longer needed

Support

• GitHub Issues: https://github.com/iHaring/homebridge-icloud-smtp/issues

When opening issues, include:

• Homebridge version
• Node.js version
• Plugin version
• Relevant log output

Credit

This plugin was inspired by the potrudeau/homebridge-messenger plugin created by Potrudeau.

License

MIT