There are some scenarios where you don't necessarily want to connect to your corporate mail server, or a public mail server like gmail - e.g. when testing a new function that possibly spams the official mail servers - or the mail server is not yet available. In such a scenario it might be a good idea to use a custom, private mail server to be able to send and receive emails locally on a test- or development-environment.
In this post I will show how to use the hMailServer and setup the ThingWorx mail extension to send emails. This post will concentrate on installing and deploying within a Windows environment. More specifically on a Windows 2012 R2 server virtual machine.
Installing hMailServer
Download and install the .NET Framework 3.5 (includes .NET 2.0 and 3.0).
In Windows Server 2012 R2 open the Server Manager and in the Configuration add roles and features.
Click through the "Role-based or feature-based installation" steps and install the ".NET Framework 3.5 Features" in case they are not already installed.
Download hMailServer via https://www.hmailserver.com/download
As always: the latest version is more stable while the beta versions might provide more functionality and additional bug fixes.
This post is based on version 5.6.6-B2383. Functionality and how-to-clicks might change in other versions.
Note: The Microsoft .NET Framework is required for this installation. In case the .NET installation fails by installing it with the hMailServer framework, it's best to cancel the installation and install the required .NET Framework manually instead of the automatic download and installation offered by hMailServer. In case of such a failure it's best to play it safe and uninstall the mail server again, install the .NET framework manually and then re-install hMailServer. (Any left-over directories should be deleted before re-installing)
For the installation, choose your path and a full installation.
Use the built-in database engine, set a password for the administrative user and install.
Configuring hMailServer
The hMailServer Administrator opens automatically after the installation - if not you will find it in the Start menu.
Connect to the default instance on the localhost. The password is the one set up during the installation process.
Add a domain (e.g. mycompany.com) and save it.
The domain will specify the domain of the mail-addresses e.g. user@domain (me@mycompany.com).
In the domain add an account.
Specify the address (e.g. noreply) and set a password (e.g. ts).
Save the new account.
The default port used for SMTP is 25. For POP3 it's 110. This is configured under Settings > Advanced > TCP/IP ports
Ensure the ports for SMPT and POP3 are not blocked by a firewall in case you run into issues later on.
This setup should *usually* work. However there might be hostname specific SMTP issues.
In case something happens / or to avoid errors in the first place, go to Settings > Protocols > SMTP > Delivery of e-mail and specific the Local host name. This should be the fully qualified hostname of the server (e.g. myserver.this.company.com).
Test hMailServer via telnet
Note: telnet needs to be installed for this test - in case it's not installed, Google can help.
Open a command line window and execute: telnet <yourhostname> 25
This will open a connection to the SMTP port of the hMailServer. Manual commands can be send to test if the basic send functions are working.
The following structure can be used for testing - it holds manual input and responses.
Username and password need to be Base64 encoded. See https://www.base64encode.org/ for Base64 conversions.
(Tip: only text, don't add additional spaces or line breaks - otherwise the hash will be quite different!)
Command / Response
Description
220 <HOSTNAME> ESMTP
Connected to host
HELO mycompany.com
Connect with domain as defined in hMailServer
250 Hello.
Connected
AUTH LOGIN
Login as authenticated user
334 VXNlcm5hbWU6
Base64 for "Username:"
bm9yZXBseUBteWNvbXBhbnkuY29t
Base64 for "noreply@mycompany.com"
334 UGFzc3dvcmQ6
Base64 for "Password:"
dHM=
Base64 for "ts"
235 authenticated.
Authentication successful
MAIL FROM: noreply@mycompany.com
Sender address
250 OK
RCPT TO: <your real mail address>
To address
250 OK
DATA
Body
354 OK, send.
Subject: sending mail via telnet
Subject line
Blank line to indicate end of subject
just a simple test!
Content
.
. indicates the end of mail
250 Queued (10.969 seconds)
Mail queued and sent with duration
QUIT
Log off telnet
221 goodbye
Connection to host lost.
Log off confirmed
Configuring ThingWorx
Download and configure the mail extension
Download the MAIL EXTENSION from the ThingWorx Marketplace
https://marketplace.thingworx.com/Items/mail-extension
In ThingWorx, click Import / Export > Extensions > Import, choose the downloaded .zip file and import it.
The Composer should be refreshed to reflect the changes introduced by the extension.
The Extension created a new Thing Template: MailServer
Create a new Thing based on the MailServer Template. In its configuration adjust the servername and port to match the hMailServer configuration, e.g. localhost and port 25. Change the Mail User Account and Password to the authentication user (e.g. noreply@mycompany.com / ts). Save the configuration to persist the changes.
In any Thing, create a new Service to send mails and notifications. Insert a snippet based on Entities > <yourMailThing> > Send Message
Call the service manually for an initial functional test. It should look similar to this... but parameters need to be adjusted to your environment:
var params = {
cc: undefined /* STRING */,
bcc: undefined /* STRING */,
subject: "sending email via ThingWorx" /* STRING */,
from: "noreply@mycompany.com" /* STRING */,
to: "<your real mail address>" /* STRING */,
body: "just a simple test!" /* HTML */
};
// no return
Things["<yourMailThing>"].SendMessage(params);
Check your mailbox for incoming messages!
What next?
The mail server can also be used to receive emails. So instead of sending mails to your regular mail address and risking a ton of spam (depending on your services and frequency of sending automated emails), you could also configure a local Outlook / Thunderbird / etc. installation and send mails directly to the noreply@mycompany.com address. Those mails can then be downloaded from hMailServer via POP3.
With this the whole send AND receive mechanism is contained within a single (virtual) machine.
View full tip
