cancel
Showing results for 
Search instead for 
Did you mean: 
cancel
Showing results for 
Search instead for 
Did you mean: 

How to install hMailServer to send emails via Mail Extensions in ThingWorx

Pearl

How to install hMailServer to send emails via Mail Extensions in ThingWorx

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.

Announcements