Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.


hMailServer is an open source email server for Microsoft Windows.

This page describes how to compile and run hMailServer in debug.

For other information about hMailServer, please go to

Building hMailServer


  • The master branch contains the latest development version of hMailServer. This version is typically not yet released for production usage. If you want to add new features to hMailServer, use this branch.

  • The x.y.z (for example 5.6.2) contains the code for the version with the same name as the branch. For example, branch 5.6.1 contains hMailServer version 5.6.1. These branches are typically only used for bugfixes or minor features.

Environment set up

Required software


You should not be compiling hMailServer on a computer which already runs a production version of hMailServer. When compiling hMailServer, the compilation will stop any already running version of hMailServer, and will register the compiled version as the hMailServer version on the machine (configuring the Windows service). This means that if you are running a production version of hMailServer on the machine, this version will stop running if you compile hMailServer. If this happens, the easiest path is to reinstall the production version.

Installing Visual Studio 2019 Community edition

  1. Download Visual Studio 2019 and launch the installation.
  2. Select the following Workloads
  • .NET desktop development
  • Desktop development with C++
  1. Select the following Individual components
  • C++ ATL for latest v142 build tools (x86 & x64)
  • Windows 10 SDK (10.0.18362.0)

3rd party libraries

Some 3rd party libraries which hMailServer relies on are large and updated frequently. Rather than including these large libraries into the hMailServer git repository, they have to be downloaded and built, currently manually. When you build hMailServer, Visual Studio will use a system environment variable, named hMailServerLibs, to locate these libraries.

Create an environment variable named hMailServerLibs pointing at a folder where you will store hMailServer libraries, such as C:\Dev\hMailLibs.

Building OpenSSL

  1. Download OpenSSL 1.1.1* from and put it into %hMailServerLibs%<OpenSSL-Version>. You should now have a folder named %hMailServerLibs%<OpenSSL-version>, for example C:\Dev\hMailLibs\openssl-1.1.1s

  2. Start a x64 Native Tools Command Prompt for VS2019.

  3. Change dir to %hMailServerLibs%<OpenSSL-version>.

  4. Run the following commands:

    Perl Configure no-asm VC-WIN64A --prefix=%cd%\out64 --openssldir=%cd%\out64 -D_WIN32_WINNT=0x600
    nmake clean   
    nmake install_sw

Building Boost

  1. Download Boost 1.72.0 from and put it into %hMailServerLibs%<Boost-Version>.
    You should now have a folder named %hMailServerLibs%<Boost-Version>, for example C:\Dev\hMailLibs\boost_1_72_0

  2. Start a x64 Native Tools Command Prompt for VS2019.

  3. Change dir to %hMailServerLibs%<Boost-Version>.

  4. Run the following commands:

    NOTE: Change the -j parameter from 4 to the number of cores on your computer. The parameter specifies the number of parallel compilations will be done.

    b2 debug release threading=multi --build-type=complete --toolset=msvc address-model=64 stage --build-dir=out64 -j 4

Building hMailServer

Visual Studio 2019 must be started with Run as Administrator.

  1. Download the source code from this Git repository.
  2. Compile the solution hmailserver\source\Server\hMailServer\hMailServer.sln. This will build the hMailServer server-part (hMailServer.exe)
  3. Compile the solution hmailserver\source\Tools\hMailServer Tools.sln. This will build hMailServer related tools, such as hMailServer Administrator and hMailServer DB Setup.
  4. Compile hmailserver\installation\hMailServer.iss (using InnoSetup) This will build the hMailServer installation program.

Running in Debug

If you want to run hMailServer in debug mode in Visual Studio, add the command argument /debug. You find this setting in the Project properties, under Configuration Properties -> Debugging.

Running tests

hMailServer source code contains a number of automated tests which excercises the basic functionality. When adding new features or fixing bugs, corresponding tests should be added. hMailServer tests are implemented using NUnit. To run them in Visual Studio, follow these steps:

NOTE: When running tests, your local hMailServer installation will be updated with test accounts. Existing domains and accounts are deleted. Each tests prepares the server configuration in different ways. In other words, do not run the automated tests in an environment where you need to preserve hMailServer data.

  1. Make sure hMailServer.exe is built and can be run. The tests will launch the service.
  2. Open the test solution, \hmailserver\test\hMailServer Tests.sln
  3. In Visual Studio, select Test Explorer from the View-menu.
  4. Locate a test to run under "RegressionTests"
  5. Right-click on a test or test category and select "Run".

You can also navigate to the source code for a test, right-click anywhere and select "Run Test(s)" to run it.

Releasing hMailServer

Without finding any serious issues:

  1. Run all integration tests on supported versions of Windows and the different supported databases.
  2. Run all server stress tests
  3. Enable Gflags (gflags /p /enable hmailserver.exe) and run all integration tests to check for memory issues
  4. Run for at least 1 week in production for
  5. Wait for at least 500 downloads of the beta version