homebridge-icloud-smtp 0.0.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iHaring
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# homebridge-icloud-smtp
+
+Homebridge dynamic platform plugin that creates virtual switches. Turning a switch on sends an email through iCloud SMTP.
+
+## Features
+
+- Create one or more HomeKit switches in Homebridge.
+- Send an email when a switch is turned on.
+- Per-switch cooldown to prevent repeated sends.
+- Per-switch retry logic for temporary SMTP failures.
+- Optional debug logging.
+
+## Requirements
+
+- Homebridge `^1.8.0 || ^2.0.0`
+- Node.js `^22.10.0 || ^24.0.0`
+- An iCloud account
+- An Apple app-specific password (required for SMTP)
+
+## Install
+
+Install from npm:
+
+```bash
+sudo npm install -g homebridge-icloud-smtp
+```
+
+Or install from the Homebridge UI:
+
+1. Open Homebridge UI.
+2. Go to **Plugins**.
+3. Search for `homebridge-icloud-smtp`.
+4. Install the plugin.
+
+## Configuration
+
+Add the platform to your Homebridge config.
+
+```json
+{
+  "platform": "ICloudSMTP",
+  "name": "iCloud SMTP",
+  "username": "you@icloud.com",
+  "password": "your-app-specific-password",
+  "debug": false,
+  "switches": [
+    {
+      "name": "Door Alert",
+      "to": "notify@example.com",
+      "subject": "Door Opened",
+      "body": "The front door was opened.",
+      "cooldown": 30,
+      "retries": 2
+    }
+  ]
+}
+```
+
+### Option Reference
+
+Platform options:
+
+- `platform` (string, required): must be `ICloudSMTP`.
+- `name` (string, recommended): display name in Homebridge.
+- `username` (string, required): your iCloud email address.
+- `password` (string, required): Apple app-specific password.
+- `debug` (boolean, optional, default `false`): enable debug logs.
+- `switches` (array, required): list of virtual mail switches.
+
+Switch options:
+
+- `name` (string, required): switch name shown in HomeKit.
+- `to` (string, required): recipient email address.
+- `subject` (string, required): email subject.
+- `body` (string, required): plain-text email body.
+- `cooldown` (number, optional, default `30`): minimum seconds between sends.
+- `retries` (number, optional, default `2`): retry count after the first failed send.
+
+## Apple App-Specific Password
+
+Apple requires app-specific passwords for third-party SMTP access.
+
+Steps:
+
+1. Sign in at [account.apple.com](https://account.apple.com/).
+2. Open **Sign-In and Security**.
+3. Select **App-Specific Passwords**.
+4. Generate a new app-specific password.
+5. Use that value as the plugin `password`.
+
+Reference: [Apple Support - Use app-specific passwords](https://support.apple.com/en-us/102654)
+
+## How It Works
+
+- The plugin registers a dynamic platform (`ICloudSMTP`).
+- Each configured switch appears as a HomeKit switch accessory.
+- Turning a switch on sends one email and then resets the switch to off.
+- Emails are sent through `smtp.mail.me.com:587` using STARTTLS (`secure: false`).
+
+## Troubleshooting
+
+- **"Missing iCloud credentials"**
+  - Ensure `username` and `password` are set in config.
+- **"No switches defined"**
+  - Add at least one entry in `switches`.
+- **Authentication failures**
+  - Verify you are using an app-specific password, not your Apple account password.
+  - Regenerate the app-specific password and update config.
+- **Switch turns on but no mail arrives**
+  - Check Homebridge logs for retry/failure messages.
+  - Verify recipient address and spam/junk folders.
+
+## Security Notes
+
+- Treat your app-specific password as a secret.
+- Do not commit credentials to Git.
+- Prefer Homebridge UI secret fields or environment-based secret handling where available.
+
+## Support
+
+- Create an issue: https://github.com/iHaring/homebridge-icloud-smtp/issues
+- Include your Homebridge version, Node.js version, and relevant log output.
+
+## License
+
+MIT

package/config.schema.json

@@ -0,0 +1,67 @@
+{
+  "pluginAlias": "ICloudSMTP",
+  "pluginType": "platform",
+  "singular": false,
+  "headerDisplay": "Send emails via iCloud SMTP when switches are triggered",
+  "schema": {
+    "type": "object",
+    "required": [
+      "username",
+      "password"
+    ],
+    "properties": {
+      "username": {
+        "title": "Enter your iCloud email address to send the emails from.",
+		"type": "string",
+		"required": true,
+        "format": "email",
+		"description": "Use the same email address that is used to login on iCloud.com when you generate the app-specific password."
+      },
+      "password": {
+        "title": "app-specific password",
+		"type": "string",
+		"description": "Generate an app-specific password on account.apple.com. Select Generate an app-specific password, then follow the steps on your screen."
+      },
+      "debug": {
+        "type": "boolean",
+        "default": false
+      },
+      "switches": {
+        "type": "array",
+        "minItems": 1,
+        "items": {
+          "type": "object",
+          "required": [
+            "name",
+            "to",
+            "subject",
+            "body"
+          ],
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "to": {
+              "type": "string",
+              "format": "email"
+            },
+            "subject": {
+              "type": "string"
+            },
+            "body": {
+              "type": "string"
+            },
+            "cooldown": {
+              "type": "number",
+              "default": 30
+            },
+            "retries": {
+              "type": "number",
+              "default": 2
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/index.js

@@ -0,0 +1,9 @@
+
+const PLATFORM_NAME = 'ICloudSMTP';
+const PLUGIN_NAME = 'homebridge-icloud-smtp';
+
+const { ICloudSMTPPlatform } = require('./platform');
+
+module.exports = (api) => {
+  api.registerPlatform(PLUGIN_NAME, PLATFORM_NAME, ICloudSMTPPlatform);
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "homebridge-icloud-smtp",
+  "displayName": "iCloud SMTP Switches",
+  "type": "commonjs",
+  "version": "0.0.7",
+  "description": "Virtual Switches to be able to send emails from Homebrige.",
+  "author": "liamharing",
+  "license": "MIT",
+  "homepage": "https://github.com/iHaring/homebridge-icloud-smtp#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/iHaring/homebridge-icloud-smtp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/iHaring/homebridge-icloud-smtp/issues"
+  },
+  "keywords": [
+    "homebridge",
+    "homebridge-plugin",
+    "plugin",
+    "homebridge plugin",
+    "virtual",
+    "virtual accessory",
+    "virtual accessories",
+    "switch",
+    "virtual switch",
+    "delay",
+    "timer",
+    "dummy"
+  ],
+  "main": "./index.js",
+  "files": [
+    "index.js",
+    "platform.js",
+    "switchAccessory.js",
+    "config.schema.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": "^22.10.0 || ^24.0.0",
+    "homebridge": "^1.8.0 || ^2.0.0"
+  },
+  "dependencies": {
+    "nodemailer": "^8.0.7"
+  }
+}

package/platform.js

@@ -0,0 +1,124 @@
+const { MailSwitchAccessory } = require('./switchAccessory');
+
+const PLATFORM_NAME = 'ICloudSMTP';
+const PLUGIN_NAME = 'homebridge-icloud-smtp';
+
+class ICloudSMTPPlatform {
+  constructor(log, config, api) {
+    this.log = log;
+    this.config = config || {};
+    this.api = api;
+    this.accessories = [];
+
+    // DEBUG FLAG (from config)
+    this.debug = this.config.debug === true;
+
+    // Debug logger helper
+    this.dlog = (msg, ...args) => {
+      if (this.debug) {
+        this.log.info(`[DEBUG] ${msg}`, ...args);
+      }
+    };
+
+    this.queue = {
+      promise: Promise.resolve(),
+      add: function (task) {
+        this.promise = this.promise
+          .then(() => task())
+          .catch(err => {
+            console.error('Queue error:', err);
+          });
+        return this.promise;
+      }
+    };
+
+    try {
+      this.validateConfig();
+    } catch (err) {
+      this.log.error(err.message);
+      throw err;
+    }
+
+    this.log.info('ICloudSMTP initialized');
+    this.dlog('Platform constructor complete');
+
+    api.on('didFinishLaunching', () => this.init());
+  }
+
+  validateConfig() {
+    this.dlog('Validating config...');
+
+    if (!this.config.username || !this.config.password) {
+      throw new Error('Missing iCloud credentials');
+    }
+
+    if (!Array.isArray(this.config.switches) || this.config.switches.length === 0) {
+      throw new Error('No switches defined');
+    }
+
+    this.dlog(`Config valid. Switch count: ${this.config.switches.length}`);
+  }
+
+  configureAccessory(accessory) {
+    this.dlog(`Restoring accessory from cache: ${accessory.displayName}`);
+    this.accessories.push(accessory);
+  }
+
+  init() {
+    this.dlog('init() called');
+
+    const validUUIDs = new Set();
+
+    for (const sw of this.config.switches || []) {
+      const uuid = this.api.hap.uuid.generate(`${sw.name}-${sw.to}`);
+      validUUIDs.add(uuid);
+
+      let accessory = this.accessories.find(a => a.UUID === uuid);
+
+      if (!accessory) {
+        accessory = new this.api.platformAccessory(sw.name, uuid);
+
+        this.api.registerPlatformAccessories(
+          PLUGIN_NAME,
+          PLATFORM_NAME,
+          [accessory]
+        );
+
+        this.log.info(`Adding new accessory: ${sw.name}`);
+        this.dlog(`Created new accessory UUID: ${uuid}`);
+      } else {
+        this.log.info(`Restoring existing accessory: ${sw.name}`);
+        this.dlog(`Matched cached UUID: ${uuid}`);
+      }
+
+      accessory.context.config = sw;
+
+      new MailSwitchAccessory(
+        this.log,
+        this.api,
+        accessory,
+        sw,
+        this.config,
+        this.queue
+      );
+    }
+
+    // Remove stale accessories
+    for (const accessory of this.accessories) {
+      if (!validUUIDs.has(accessory.UUID)) {
+        this.log.info(`Removing stale accessory: ${accessory.displayName}`);
+        this.dlog(`Unregistering UUID: ${accessory.UUID}`);
+
+        this.api.unregisterPlatformAccessories(
+          PLUGIN_NAME,
+          PLATFORM_NAME,
+          [accessory]
+        );
+      }
+    }
+
+    this.dlog('init() complete');
+  }
+}
+
+module.exports = { ICloudSMTPPlatform };

package/switchAccessory.js

@@ -0,0 +1,95 @@
+
+const nodemailer = require('nodemailer');
+
+class MailSwitchAccessory {
+  constructor(log, api, accessory, swConfig, platformConfig, queue) {
+    this.log = log;
+    this.api = api;
+    this.accessory = accessory;
+    this.swConfig = swConfig;
+    this.platformConfig = platformConfig;
+    this.queue = queue;
+    this.lastSent = 0;
+
+    this.service =
+      accessory.getService(api.hap.Service.Switch) ||
+      accessory.addService(api.hap.Service.Switch, swConfig.name);
+
+    accessory.getService(api.hap.Service.AccessoryInformation)
+      .setCharacteristic(api.hap.Characteristic.Manufacturer, 'Custom')
+      .setCharacteristic(api.hap.Characteristic.Model, 'iCloud SMTP Switch')
+      .setCharacteristic(api.hap.Characteristic.SerialNumber, swConfig.name);
+
+    this.service
+      .getCharacteristic(api.hap.Characteristic.On)
+      .onSet(this.setState.bind(this))
+      .onGet(() => false);
+
+    this.transporter = nodemailer.createTransport({
+      host: 'smtp.mail.me.com',
+      port: 587,
+      secure: false,
+      auth: {
+        user: platformConfig.username,
+        pass: platformConfig.password
+      }
+    });
+  }
+
+  logPrefix() {
+    return `[${this.swConfig.name}]`;
+  }
+
+  async setState(value) {
+    if (!value) return;
+
+    const now = Date.now();
+    const cooldownMs = (this.swConfig.cooldown || 30) * 1000;
+
+    this.log.info(this.logPrefix() + ' triggered');
+
+    if (now - this.lastSent < cooldownMs) {
+      this.log.warn(this.logPrefix() + ' cooldown active');
+      return this.reset();
+    }
+
+    this.lastSent = now;
+
+    await this.queue.add(() => this.sendWithRetry());
+
+    this.reset();
+  }
+
+  async sendWithRetry() {
+    const retries = this.swConfig.retries || 2;
+
+    for (let i = 1; i <= retries + 1; i++) {
+      try {
+        this.log.info(this.logPrefix() + ' sending attempt ' + i);
+
+        await this.transporter.sendMail({
+          from: this.platformConfig.username,
+          to: this.swConfig.to,
+          subject: this.swConfig.subject,
+          text: this.swConfig.body
+        });
+
+        this.log.info(this.logPrefix() + ' email sent');
+        return;
+      } catch (e) {
+        this.log.warn(this.logPrefix() + ' attempt ' + i + ' failed');
+        if (i > retries) {
+          this.log.error(this.logPrefix() + ' all retries failed');
+        }
+      }
+    }
+  }
+
+  reset() {
+    setTimeout(() => {
+      this.service.updateCharacteristic(this.api.hap.Characteristic.On, false);
+    }, 500);
+  }
+}
+
+module.exports = { MailSwitchAccessory };