UltraSMTP3 HSPI User’s Guide
A HomeSeer HS3 plug-in used to send reliable e-mail notifications using a queuing mechanism.
Copyright © 2015
Revised 09/11/2015
This document contains proprietary and copyrighted information and may not be copied, reproduced, translated, or reduced to any electronic medium without prior consent, in writing, from [email protected].
2
Table of Contents Introduction .................................................................................................................................................. 4
Intended Audience .................................................................................................................................... 4
UltraSMTP3 HSPI Overview........................................................................................................................... 4
How It Works ............................................................................................................................................ 4
Features .................................................................................................................................................... 4
Requirements ............................................................................................................................................ 4
UltraSMTP3 HSPI Installation ........................................................................................................................ 5
Downloading the HomeSeer Plug-in ......................................................................................................... 5
UltraSMTP3 HSPI Configuration .................................................................................................................... 5
Web Page Layout ...................................................................................................................................... 5
Screenshot ............................................................................................................................................ 5
Options ...................................................................................................................................................... 5
SMTP Profiles ............................................................................................................................................ 6
Screenshots ........................................................................................................................................... 7
Adding a New SMTP Profile .................................................................................................................. 8
Modifying an SMTP Profile.................................................................................................................... 8
Deleting an Existing SMTP Profile ......................................................................................................... 8
UltraSMTP3 HomeSeer Devices ................................................................................................................ 9
UltraSMTP3 HSPI SMTP Logs......................................................................................................................... 9
Search the SMTP Logs by Date .............................................................................................................. 9
Screenshot ............................................................................................................................................ 9
Search the SMTP Logs by Queue Id ...................................................................................................... 9
Screenshot .......................................................................................................................................... 10
UltraSMTP3 HSPI Triggers ........................................................................................................................... 10
UltraSMTP3 Delivery Trigger ............................................................................................................... 10
UltraSMTP3 HSPI Trigger Actions ................................................................................................................ 10
UltraSMTP3 Send E-mail ......................................................................................................................... 10
Action Properties ................................................................................................................................ 10
Device Replacement Variables................................................................................................................ 11
3
Device Value Replacement Variables Using Math .................................................................................. 11
Other Supported HomeSeer Replacement Variables ............................................................................. 12
Example Usage ........................................................................................................................................ 12
Screenshot .............................................................................................................................................. 13
UltraSMTP3 HSPI Trigger Conditions .......................................................................................................... 13
UltraSMTP3 HSPI API Reference ................................................................................................................. 13
SendMail Function .................................................................................................................................. 13
Example ............................................................................................................................................... 14
4
Introduction UltraSMTP3 is a HomeSeer HS3 plug-in used to send reliable e-mail notifications. It can be used to send
e-mail notifications using either the standard SMTP port or using SMTP authentication via SSL/TLS.
Intended Audience This document is intended for the HomeSeer user that has chosen to install and configure the
UltraSMTP3 HomeSeer Plug-in.
UltraSMTP3 HSPI Overview
How It Works
When you send an e-mail notification using UltraSMTP3, the e-mail is queued to disk and a unique queue identifier is assigned to the message. If a message cannot be sent to any of the configured SMTP mail systems, the messages is re-queued and retried until either the message is delivered or the user configurable delivery attempts are exceeded. The UltraSMTP3 HSPI Send E-Mail action supports a wide range of HomeSeer replacement variables allowing the message to include information such as device properties, global variables and HomeSeer logs lines.
Features
Multiple threading allows UltraSMTP3 HSPI to manage the delivery of e-mail notifications
without disrupting the performance of HomeSeer.
Supports sending e-mail notifications using the standard SMTP port.
Supports sending e-mail notifications using authentication via SSL/TLS (e.g. gmail.com,
hotmail.com, etc.)
Support for an unlimited number of SMTP server profiles.
Each message is assigned a queue identifier for tracking purposes. An underlying database tracks the delivery status of each message. Plain text or HTML message e-mail notifications are supported. The body of the e-mail message can contain a wide range of HomeSeer replacement variables. HomeSeer event trigger for e-mail delivery status of a message. Error Try/Catch logic to ensure plug-in doesn't fail with an unhandled exception.
Requirements Homeseer 3 or greater
The SMTP server details associated with your e-mail accounts.
5
UltraSMTP3 HSPI Installation
Downloading the HomeSeer Plug-in 1. From your HomeSeer web page, select PLUG-INS > Manage.
2. Click the + icon next to Additional Interfaces to expand the list of available HomSeer3 plug-ins.
3. Click the + icon next to the “Utilities” category, then click the checkbox next to the UltraSmtp3
(SMTP Email) package to mark the plug-in for installation.
4. Under “Pending Updates/Installs”, click the Download and Install button.
5. Once the installer finishes, find the UltraSmtp3 plug-in under Installed Plug-Ins, then enable it.
UltraSMTP3 HSPI Configuration
Web Page Layout The UltraSMTP3 plug-in has four web pages that provide access the available features of the plug-in.
Screenshot
The available web pages are as follows:
1. Status – Displays the plug-in and the SMTP queue status.
2. Options – Displays and allows you to change the options associated with the plug-in.
3. SMTP Profiles – Displays and allows you to add, modify, delete and test SMTP profiles.
4. SMTP Logs – Provides the ability to quickly query and display delivery information for each
message sent using UltraSMTP3 HSPI.
Options All options are set from the Options web page. The following options are supported:
1. Maximum Delivery Attempts – Specify the maximum number of delivery attempts before
marking the message undeliverable. The default is 10.
6
2. Authorized User Roles – Specify the HomeSeer users authorized to access the UltraSMTP3 web
page.
3. Register Link – If set to Yes, the UltraSMTP3 button will be displayed on all web pages.
4. Debug Mode – If set to Yes, the plug-in will write verbose logging to the HomeSeer log file.
SMTP Profiles The SMTP Profiles web page allows you to add, modify, delete and test SMTP profiles. An SMTP profile
contains the SMTP settings associated with an e-mail service provider. Having multiple SMTP profiles
defined increases the probability a message being delivered if your primary SMTP profile is unreachable.
Before you begin to configure the UltraSMTP3 plug-in, you’ll need to obtain the SMTP server
information for each e-mail provider you wish to use. I am including information for the popular e-mail
service types below:
1. Unauthenticated SMTP – an SMTP server included with most Internet Service Provider
accounts.
Generic Unauthenticated SMTP Profile Information
SMTP Server: {check with your provider}
SMTP Port: 25
Use SSL: No
User Id: Leave blank
User Password: Leave blank
Default Mail-From E-mail Address: Your e-mail e-mail address
2. Authenticated SMTP – an SMTP server included with most Internet Service Provider accounts.
Generic Authenticated SMTP Profile Information
SMTP Server: {check with your provider}
SMTP Port: {check with your provider}
Use SSL: {check with your provider}
User Id: {check with your provider}
User Password: {check with your provider}
Default Mail-From E-mail Address: Your e-mail address
3. Hotmail – a free web-based email service provided by Microsoft.
Hotmail SMTP Profile Information
SMTP Server: smtp.live.com
SMTP Port: 587
Use SSL: Yes
User Id: Your Hotmail e-mail address
User Password: Your Hotmail e-mail password
Default Mail-From E-mail Address: Your Hotmail e-mail address
4. Gmail – a free web-based e-mail service provided by Google.
Gmail SMTP Profile Information
SMTP Server: smtp.gmail.com
SMTP Port: 587
Use SSL: Yes
7
User Id: Your Gmail e-mail address
User Password: Your Gmail e-mail password
Default Mail-From E-mail Address: Your Gmail e-mail address
5. Yahoo – a subscription based web-based e-mail service provided by Yahoo.
Gmail SMTP Profile Information
SMTP Server: plus.smtp.mail.yahoo.com
SMTP Port: 587
Use SSL: Yes
User Id: Your Yahoo e-mail address
User Password: Your Yahoo e-mail password
Default Mail-From E-mail Address: Your Yahoo e-mail address
6. GoDaddy – a subscription based e-mail service provided by GoDaddy.
Gmail SMTP Profile Information
SMTP Server: smtpout.secureserver.net
SMTP Port: 80
Use SSL: No
User Id: Your GoDaddy e-mail address
User Password: Your GoDaddy e-mail password
Default Mail-From E-mail Address: Your GoDaddy e-mail address
Screenshots
8
Adding a New SMTP Profile
1. Click on the UltraSMTP3 > SMTP Profiles button.
2. Click the New button towards the top left of the web page.
3. Enter the SMTP server fully qualified domain.
4. Enter the SMTP server port number.
5. Use SSL should be set to “Yes” only if the SMTP server requires a sure connection (e.g. SSL/TLS).
6. Enter your e-mail address for the SMTP server provided. This e-mail address must be supported
by the SMTP server associated with the SMTP profile.
7. If the SMTP server requires authentication, then enter the User Id and User Password in the
fields provided. Otherwise, leave the User Id and User Password fields empty.
8. To add the SMTP profile, simply click on the Add New icon
Modifying an SMTP Profile
1. Click on the UltraSMTP3 > SMTP Profiles button.
2. Find the SMTP Profile you want to edit, and then click the Edit action link.
3. Edit the values as needed, then press the Update button.
4. To cancel the changes, simply press the Close dialog icon in the upper right.
Deleting an Existing SMTP Profile
1. Click on the UltraSMTP3 > SMTP Profiles button.
2. Find the SMTP Profile you want to delete, and then click the Delete action link.
3. Confirm you want to delete the profile by pressing Delete.
4. To cancel the delete, simply press the Close dialog icon in the upper right.
9
UltraSMTP3 HomeSeer Devices The UltraSMTP3 plug-in does not create any HomeSeer devices.
UltraSMTP3 HSPI SMTP Logs The SMTP Logs web page allows you to query and display delivery information for each message sent
using UltraSMTP3 HSPI.
Search the SMTP Logs by Date
1. Click on the UltraSMTP3 > SMTP Logs button.
2. Select the “From” date and time, then select the “To” date and time.
3. Click the Filter button to display all messages received between the date and times specified in
the step above.
Screenshot
Search the SMTP Logs by Queue Id
1. Click on the UltraSMTP3 > SMTP Logs button.
2. Enter the Queue Id in the field provided.
3. Select the “From” date and time, then select the “To” date and time.
4. Click the Filter button to display the message with the Queue Id provided.
10
Screenshot
UltraSMTP3 HSPI Triggers You can create HomeSeer events using any of the supported triggers below.
UltraSMTP3 Delivery Trigger
This trigger can be used to run a HomeSeer event whenever a messages delivery is attempted. This may
be useful if you want to receive a voice alert if an e-mail notification does not succeed.
UltraSMTP3 HSPI Trigger Actions
UltraSMTP3 Send E-mail This action causes the plug-in to generate an e-mail to the recipient specified in the HomeSeer event.
The UltraSMTP3 HSPI Send E-Mail action supports a wide range of HomeSeer replacement variables
allowing the message to include information such as device details, global variables and logs lines.
Action Properties Action Properly Name Action Property Description
E-mail Action The specified event action (e.g. Send E-mail)
Recipient The recipient e-mail address (e.g. [email protected])
Subject The subject of the e-mail notification (e.g. E-mail Notification)
Body The body of the e-mail. If you want to send an HTML formatted messages, you must include the start and end
HTML tags (e.g. <html><body></body></html>
Note: The e-mail body can contain a wide range of HomeSeer replacement variables allowing the message to
include information such as device details, global variables and logs lines.
Attachment Path The full path to the file or files you want to attachment to the e-mail.
Note: You can include file name wild cards to include multiple files of the same type (e.g. c:\some folder\*.gif).
11
Device Replacement Variables Simply enter the replacement variable into the body section of the UltraSMTP3 Send E-mail action and
the UltraSMTP3 HSPI will replace it with the current value for the specified device.
Replacement Variable By Device Address Replacement Variable Description
$$DNA:{address}: Device Name
$$DLA:{address}: Device Location 1
$$DlA:{address}: Device Location 2
$$DTA:{address}: Device Type
$$DCA:{address}: Device Last Change
Replacement Variable By Device Code Replacement Variable Description
$$DNA:{code}: Device Name
$$DLA:{ code }: Device Location 1
$$DlA:{ code }: Device Location 2
$$DTA:{ code }: Device Type
$$DCA:{ code }: Device Last Change
Replacement Variable By Device Ref Replacement Variable Description
$$DNR:{ref}: Device Name
$$DLR:{ref}: Device Location 1
$$DlR:{ref}: Device Location 2
$$DTR:{ref}: Device Type
$$DCR:{ref}: Device Last Change
Note: Any of the HomeSeer replacement variables may also be used.
For example, if you want to provide the device name, device location, device value and device last change in an e-mail for HomeSeer device A1, then you would enter the following text into the body section of the UltraSMTP3 Send E-mail action:
The device value for $$DNC:A1: located in the $$DLC:A1: is now $$DVC:A1:.
This device last changed state on $$DCC:A1:.
Device Value Replacement Variables Using Math You can also perform simple math on HomeSeer device values: Replacement Variable Replacement Variable Description
$$Math.Divide( $$DVA:{address}:, $$DVA:{address}:) Divide device value 1 and device value 2
$$Math.Multiply( $$DVA:{address}:, $$DVA:{address}:) Multiply device value 1 and device value 2
$$Math.Add( $$DVA:{address}:, $$DVA:{address}:) Add device value 1 and device value 2
$$Math.Subtract( $$DVA:{address}:, $$DVA:{address}:) Subtract device value 1 and device value 2
For example, if you wanted to report the inside temperature (A1) and outside temperature (A2) and the difference, you could use the following text:
$$DNA:Station1-todays-low: $$DVA:Station1-todays-low: $$DNA:Station1-todays-high: $$DVA:Station1-todays-high:
The temperature difference between the high and low is: $$Math.Subtract($$DVA:Station1-todays-high:, $$DVA:Station1-todays-low:)
12
Results in the following after the variables are replaced with the actual values:
S1 Todays Low: 28 S1 Todays High: 43 The temperature difference between the high and low is: 15
Other Supported HomeSeer Replacement Variables Replacement Variable Replacement Variable Description
$$GetVar:[VariableName] The value of a HomeSeer variable.
$$HS.Logs The contents of the last 10 HomeSeer log lines.
$$HS.WANIP The name and IP address of your HomeSeer WAN interface.
$$HS.LANIP The IP address of your HomeSeer local LAN interface.
$$HS.GetLastRemoteIP The IP address of the last system that accessed your HomeSeer
system. $$HS.HSMemoryUsed The value of the memory used by HomeSeer.
$$HS.SystemUptime The system uptime since last restart.
$$HS.Sunrise The time of sunrise.
$$HS.Sunset The time of sunset.
For example, if you wanted to include the value of HomeSeer global variable “My Value” and include the last 10 HomeSeer log lines, you could use the following string:
The value of HomeSeer variable “My Value” is: $$GetVar:[My Value]
The last 10 lines of my HomeSeer logs are:
$$HS.Logs
Example Usage
Send a daily status notification showing the status of the most important devices in your home. Include additional information in e-mail notifications not available using the built in replacement
variables provided by HomeSeer. Send an e-mail attachment of a picture captured by your web camera.
13
Screenshot
UltraSMTP3 HSPI Trigger Conditions This plug-in does not have any HomeSeer trigger conditions defined.
UltraSMTP3 HSPI API Reference
SendMail Function This function sends e-mail using one of the pre-defined SMTP Profiles.
Public Function SendMail(ByVal ToAddr As String, _ ByVal Subject As String, _ ByVal Body As String, _ ByVal AttachmentPaths() As String) As Boolean
ToAddr is the e-mail address of the intended recipient.
Subject is subject of the e-mail message.
Body is contents of the e-mail message.
AttachmentPaths is the string array for each file that should be attached to the e-mail mesasge.
14
Example
Sub Main(ByVal parm As Object)
Dim ToAddr As String = "[email protected]"
Dim Subject As String = "UltraSMTP3 Notification"
Dim Body As String = "This is an e-mail notification sent on $date."
Dim Attachments() As String = Nothing
hs.PluginFunction("UltraSMTP3", "", " SendMail", New Object() {ToAddr,Subject,Body,Attachments})
End Sub
