Local mail server with hMailServer

As developers we want to be able to test everything we program before it goes live. When we write code to push out emails to our customers or visitors, we want to be confident it’s going to arrive at the destination, looking the way we expect. Most local windows server setups with XAMPP or WAMP won’t by default be setup with a mail server and setting one up can be a pain. Luckily there’s some great software out there to make everything a lot easier. Queue hMailServer…


This quick step-by-step guide should get you up and running with local mail functionality and a test script in under 20 minutes.

Start by going to www.hmailserver.com, click download in the menu and choose the latest build (at time of writing this is 5.3.3).

Browse to the download location and open the exe file.

Click next through the installation screens with the default settings, add an administrator password and connect when requested on the final screen.

Installation hMailServer

Once the program loads, select the ‘Domains’ option on the left hand side, and click ‘Add’. The domain will be used to receive your test emails, in my example I have used ‘activelab.dev’. Enter the domain you wish to use and click ‘Save’. 

Domain Setup hMailServer

You’ll see this now adds several folder options under your new domain on the left side options. Go to the ‘Accounts’ folder and click ‘Add’. Under the ‘General’ tab you can now add a test account with an address and password under your test domain (you can change these or add more later if you need to). Add a couple for testing purposes (in the example I have added a personal one david@activelab.dev and a general one support@activelab.dev).

Setup Account hMailServer

Next we need to setup our mail client, configuration is easiest with Thunderbird so for this setup that’s what we’ll be using.

Download thunderbird from the Mozilla web site and run the installation file. Launch the application on completion.

On the welcome screen, choose to ‘Skip this and use my existing email’, or if you already have Thunderbird installed then create a new account. Enter the details of the account you setup, click ‘Continue’ and then click ‘Manual Config’. Here you’ll notice that the incoming IMAP and outgoing SMTP have been set to your domain, change these both to ‘localhost’ or ‘’, make sure the ‘Username’ is set to the full address with the domain, click ‘Re-Test’ to make sure this works and then click ‘Done’. (If you get a message ‘Thunderbird failed to find the account settings’ take a look at the ‘Gothas’ section below). You’ll lastly be asked to accept a security warning.

Repeat this process (add new account) for the second account you added previously.


Trying it out

 You can now test your configuration by loading up Thunderbird and sending a new email from one of your accounts to the other. This will confirm your email configuration is working, next we can try it with some code:

$to = 'david@local.dev';
$subject = 'Test Mail';
$message = 'Hello World!';
$headers = 'From: support@activelab.dev' . "\r\n" .
'Reply-To: support@activelab.dev' . "\r\n" .
'X-Mailer: PHP/' . phpversion();
mail($to, $subject, $message, $headers);

This email should land in your mailbox instantly when you run the code, if it doesn't, check out the next section...

Gotchas (and troubleshooting)

Code not working

If you find that your email came through fine in Thunderbird but not using your code, this would suggest a problem with your server setup. Check that your php.ini settings are configured to send SMTP using localhost using port 25 as below:

[mail function]
SMTP = localhost
smtp_port = 25

In a recent project I had this issue, and so I also adjusted the zend project to pickup the local environment to ensure that it would work for other developers without them having to change their settings. If you're using an HtmlMailer class like the one outlined in ZendCasts then this simple bit of code will do the trick in the sendHtmlTemplate method:

if(APPLICATION_ENV == "development")
     $config = array('port'=>25);
     $transport = new Zend_Mail_Transport_Smtp('localhost', $config);

Thunderbird can't connect to my account

If like me you didn’t use the domain in the username field to start with, thunderbird will make multiple attempts with your saved password which will trigger the ‘Auto-ban’ feature in hMailServer. This will leave you confused with a message from Thunderbird during setup stating that it cannot find the settings for your account. To fix this problem, change the username field to contain the full address (see Mail Account Setup screenshot above) then load up hMailServer and go to ‘Advanced’ > ‘IP Ranges’ and then delete the ‘Autoban: …’ record highlighted in red. Go back to Thunderbird and re-test your account. Note you would get the same autoban problem if you got your password wrong several times.

hMailServer Gotcha

Happy emailing.

Sign Up

NEXT: Protecting your email account from being hacked

What happens when someone steals your password and gains access to your email address? Hacked email accounts and identity theft are all too common these days, and being a victim can cause you all sorts of problems. This article looks at some steps you can take to protect yourself.

comments powered by Disqus

Popular Tags

Need a web developer?

If you'd like to work with code synthesis on your next project get in touch via the contact page.