Hmail Server

Hmail Server

hMailServer is a free, open-source mail server for Windows and Linux: SMTP, IMAP and POP3, with the transport security, sender authentication and anti-abuse machinery a mail server needs in 2026. This wiki documents hMailServer 6.3.1, the modernised fork maintained by Christopher Holloway / Progressive Robot Ltd, licensed AGPL-3.0-or-later.

Download: the latest release is a single x64 installer that upgrades any earlier hMailServer in place, and — new in 6.3.0 — a .deb, an .rpm and an AppImage for x86-64 and AArch64 Linux. Source and issues: the repository. What is planned: Roadmap.md.

At a glance

Current release	6.3.2, build 41, published 13 September 2026
Database schema	6038 — seven steps since 6.3.1 (6032 to 6038: the webmail's tables and columns and the SURBL expected result); the installer runs DBUpdater, which applies them
Platform	Windows x64 — a single Inno Setup installer, the service runs as a Windows service — and, new in 6.3.0, Linux on x86-64 and AArch64: a .deb, an .rpm, a PKGBUILD and an AppImage, with a systemd unit that runs the server as its own user. One source tree builds both
Licence	AGPL-3.0-or-later, with an SPDX header on every source file
Protocols served	SMTP (with ESMTP: SIZE, 8BITMIME, PIPELINING, CHUNKING, BINARYMIME, SMTPUTF8, ENHANCEDSTATUSCODES, DSN, STARTTLS, AUTH), IMAP4rev1 and IMAP4rev2, POP3, ManageSieve
Database backends	SQL Server Compact (built in, no setup), Microsoft SQL Server, MySQL/MariaDB, PostgreSQL
Administration	hMailCP, a .NET 10 desktop Control Panel over COM — 55 pages in eight groups; a REST API of 82 routes over 68 paths, which since 6.3.0 write as well as read; the Control Deck, an administration page in the browser at /; and a webmail for users at /portal
Regression suite	2,175 tests
This wiki	51 pages, arranged as the five journeys below. The reference pages cite file:line into the repository, so any claim on them can be checked against the code

The system at a glance

flowchart TB
  subgraph EDGE["Listeners"]
    L1["SMTP 25 / 587 / 465"]
    L2["IMAP 143 / 993"]
    L3["POP3 110 / 995"]
    L4["ManageSieve, metrics,<br/>REST API and portal,<br/>public web services"]
  end

  subgraph CORE["The server process"]
    ACC["Accept and save:<br/>anti-spam, scripts, signatures,<br/>Authentication-Results, archive"]
    Q["Delivery queue"]
    DEL["Delivery: virus scanning, global rules,<br/>DKIM signing, mirroring"]
    LOC["Local delivery:<br/>rules, Sieve, forwarding,<br/>lists, public folders"]
    EXT["External delivery:<br/>routes or MX, MTA-STS,<br/>DANE, TLS"]
    SCH["Scheduler: backups, greylist cleaner,<br/>retention, TLS-RPT and DMARC reporters"]
    FET["External account fetching"]
  end

  subgraph STORE["State"]
    DB[("Database:<br/>SQL CE, MSSQL,<br/>MySQL, PostgreSQL")]
    FS["Message store on disk"]
  end

  subgraph OUTS["Outside"]
    DNS["DNS resolvers"]
    SA["SpamAssassin spamd"]
    CAV["ClamAV clamd"]
    REM["Other mail servers"]
  end

  L1 --> ACC
  ACC --> Q
  Q --> DEL
  DEL --> LOC
  DEL --> EXT
  EXT --> REM
  L2 --> FS
  L3 --> FS
  ACC --> FS
  ACC --> DB
  LOC --> FS
  SCH --> DB
  FET --> ACC
  ACC -.-> SA
  DEL -.-> CAV
  ACC -.-> DNS
  EXT -.-> DNS
  L4 --> DB

Loading

Solid lines are the path a message takes; dotted lines are the services the server calls out to. Architecture maps this onto the source tree; Ports Reference covers every listener and every outbound connection.

How this wiki is organised

Five journeys, and one reference spine that every journey lands on. The sidebar is in the same order, so the group you are reading from is the group you are in.

flowchart LR
  subgraph J1["1. Install and run"]
    direction TB
    A1["Before You Install"] --> A2["Installing hMailServer"]
    A2 --> A3["The Control Panel"]
    A3 --> A4["Your First Domain<br/>and Mailbox"]
    A4 --> A5["Connecting a<br/>Mail Client"]
    A5 --> A6["DNS for Your Domain"]
  end

  subgraph J2["2. Secure it"]
    direction TB
    B1["Encryption and<br/>Certificates"] --> B2["Stopping Spam"]
    B2 --> B3["Stopping Viruses"]
    B3 --> B4["Security Hardening"]
  end

  subgraph J3["3. Operate it"]
    direction TB
    C1["Monitoring and Health"] --> C2["Backup and Restore"]
    C2 --> C3["Troubleshooting and<br/>Diagnosing Stalled Mail"]
    C3 --> C4["Upgrading hMailServer"]
    C4 --> C5["Warm Standby,<br/>High Availability"]
  end

  subgraph J4["4. Extend it"]
    direction TB
    D1["Rules and Sieve"] --> D2["Aliases, Lists,<br/>Public Folders"]
    D2 --> D3["Routes and Relays"]
    D3 --> D4["COM API and<br/>event scripts"]
    D4 --> D5["The REST API"]
  end

  subgraph J5["5. Contribute to it"]
    direction TB
    E1["Project Handbook"] --> E2["Architecture"]
    E2 --> E3["Contributing"]
    E3 --> E4["Regression Test<br/>Environment"]
    E4 --> E5["Release Process"]
  end

  REF["Look it up:<br/>Settings Reference, Ports Reference,<br/>Control Panel Reference, APIs Reference,<br/>Capabilities and Configuration,<br/>Changes Since 6.2.10, Glossary"]

  A6 --> B1
  B4 --> C1
  C5 --> D1
  D5 --> E1

  A3 -.-> REF
  B2 -.-> REF
  C3 -.-> REF
  D4 -.-> REF
  E2 -.-> REF

Loading

Solid arrows are the order the pages are meant to be read in. The dotted arrows say the same thing five times: every journey ends up in the reference pages, which are generated from the code rather than written from memory.

Three kinds of page, and it is worth knowing which one you are reading:

Kind	How to recognise it	What to trust it for
Guide (26 pages)	Opens with a note saying it began as a chapter of the 6.2.10 manual and has been corrected against the 6.2.28 source	Doing the job. Screenshots are from a 6.2.10-era build, and the installer shots from a 6.2.11 one; each caption says when the current dialog differs
Generated reference	Opens with a scope paragraph naming the commit it was read at, and cites file:line on nearly every claim	Exact values: defaults, limits, route tables, key names. Where a guide and a reference disagree, the reference is right
Repository document	Copied from a file in the repository. Eight say so in a "Source of truth" note at the top; the runbooks copied without that note are all listed, with the file each came from, in Runbooks Digest	The project position: governance, security policy, assurance, release rules, and the operational runbooks

Start here

New to hMailServer? Read in this order: What hMailServer Is and Is Not → How Email Works → Before You Install → Installing hMailServer → The Control Panel → Your First Domain and Mailbox → Connecting a Mail Client → DNS for Your Domain → Encryption and Certificates → Stopping Spam.

flowchart LR
  A["What hMailServer<br/>Is and Is Not"] --> B["How Email Works"]
  B --> C["Before You Install"]
  C --> D["Installing hMailServer"]
  D --> E["The Control Panel"]
  E --> F["Your First Domain<br/>and Mailbox"]
  F --> G["Connecting a<br/>Mail Client"]
  G --> H["DNS for Your Domain"]
  H --> I["Encryption and<br/>Certificates"]
  I --> J["Stopping Spam"]
  J --> K["Live"]
  H -.-> L["Ports Reference"]
  I -.-> L

Loading

Mail will flow after step F. It will land in inboxes rather than spam folders only after steps H and I, which is why the two are in the path and not in an appendix.

Step E is where the installer leaves you: the Control Panel Welcome page, which is built on the same idea as this one — a small set of tiles pointing at the job you actually came to do, and a search box over every page.

Two things have moved on since this capture: the tree on the left has been regrouped, and 6.2.28 registers 55 pages in eight groups, mapped in Control Panel Reference; and the page now opens with twelve outcome-shaped task rows above these six area tiles.

Running a server already? Upgrading hMailServer and Changes-Since-6210 say what moves between versions; the Settings Reference is the complete hMailServer.INI reference, generated from the code.

Something is wrong — where do I go?

flowchart LR
  S(["Symptom"])
  S --> R1["Nothing arrives<br/>from outside"]
  S --> R2["I cannot send"]
  S --> R3["My mail lands in<br/>the spam folder"]
  S --> R4["A message is sitting<br/>in the queue"]
  S --> R5["A mail client cannot<br/>connect, or cannot log in"]
  S --> R6["The Control Panel<br/>will not connect"]
  S --> R7["The service<br/>will not start"]
  S --> R8["Something was refused<br/>and I want to know why"]

  R1 --> P1["Troubleshooting 19.2,<br/>then Ports Reference and<br/>DNS for Your Domain"]
  R2 --> P2["Troubleshooting 19.3,<br/>then Routes and Relays"]
  R3 --> P3["Troubleshooting 19.4,<br/>then DNS for Your Domain"]
  R4 --> P4["Diagnosing Stalled Mail"]
  R5 --> P5["Troubleshooting 19.6,<br/>then Connecting a Mail Client<br/>and Ports Reference"]
  R6 --> P6["Troubleshooting 19.5"]
  R7 --> P7["Troubleshooting 19.9"]
  R8 --> P8["Stopping Spam, then<br/>Monitoring and Health<br/>for the log to read"]

Loading

The numbers are the section headings inside Troubleshooting. Read §19.1 Start here, always before any of them: it names the log to open first, which is the step people skip.

Find it fast

I want to…	Go to
Understand what this software does and does not do	What hMailServer Is and Is Not
Learn how mail actually moves, with the protocol conversations	How Email Works
Install it for the first time	Before You Install, then Installing hMailServer
Add my first domain and mailbox	Your First Domain and Mailbox
Tell a user what to type into Outlook or Thunderbird	Connecting a Mail Client
Know which port to open, and which to close	Ports Reference
Publish SPF, DKIM, DMARC, MTA-STS, TLS-RPT or TLSA	DNS for Your Domain
Get a certificate, automatically or by hand	Encryption and Certificates
Stop spam, or find out why something was refused	Stopping Spam
Keep a virus scanner in the delivery path	Stopping Viruses
Sort mail into folders, or let a user write their own filters	Rules and Sieve
Make one address reach several people	Aliases Lists and Public Folders
Send everything through a smart host	Routes and Relays
Work out why a message is stuck in the queue	Diagnosing Stalled Mail
Move a configured installation to another directory or drive	Relocating an Installation
Run hMailServer on Linux, on x86-64 or AArch64	Installing on Linux
Run it as a container, from the image on GHCR	Running in a Container
Look up an hMailServer.INI key and its default	Settings Reference
Find the Control Panel page behind a setting	Control Panel Reference
Know which protocol keyword the server actually advertises	Capabilities and Configuration
Script the server, or call it over HTTP	The COM API and Scripting, APIs Reference, The REST API
Back it up, or restore it	Backup and Restore
Move from SQL CE to a real database server	Migrating the Database Backend
Survive the loss of the machine	Warm Standby, High Availability Runbook
Watch it with Prometheus or an OpenTelemetry collector	Monitoring and Health
Harden it before it goes public	Security Hardening
Report a vulnerability	Security Policy
Know what changed between two versions	[[Changes-Since-6210
Look up a term I do not know	Glossary
Build it, test it, or send a patch	Project Handbook, Contributing
Decide whether to run this on the public internet	Assurance Case

Every page, by what you are trying to do

The other 48 pages of this wiki, grouped exactly as the sidebar groups them.

Start here

Page	What it answers
What hMailServer Is and Is Not	What the software owns, what it leaves to your DNS provider and your mail clients, and what the licence requires of you
How Email Works	SMTP, IMAP, POP3 and DNS for someone who has not run a mail server, with the real conversations and where each filter sits in them

1. Install and run

Page	What it answers
Before You Install	The pre-flight list: hardware, a fixed address and its reverse DNS, the host name, the database choice and the certificate plan — decided before the installer runs, because two of them are awkward to change afterwards
Installing hMailServer	The installer wizard screen by screen, the silent install, the administrator password, and what the first start creates
The Control Panel	hMailCP: connecting to the service, the navigation tree of 55 pages in eight groups, the Ctrl+K search over every page and setting, the Welcome and Dashboard pages
Your First Domain and Mailbox	Adding a domain and an account, and proving to yourself that delivery works before anyone else depends on it
Connecting a Mail Client	Exactly what to give a user for Outlook, Thunderbird and phones; which port and which encryption; autoconfig and autodiscover so they need not be told at all
DNS for Your Domain	MX, SPF, DKIM, DMARC, MTA-STS, TLSA and TLS-RPT, with the record text and the order to publish them in. The most consequential page in the wiki for whether your mail is delivered

2. Secure it

Page	What it answers
Encryption and Certificates	Getting a certificate — ACME automatically, or by hand — binding it to ports, the TLS versions and ciphers, DANE and MTA-STS, and what a client sees when it is wrong
Stopping Spam	The filter layers in the order the server runs them, from connection checks to SpamAssassin, with greylisting, quarantine, and how to read the refusal the sender got
Stopping Viruses	Why the server scans nothing itself, how ClamAV and external scanners are wired in, blocked attachments, and what happens to mail when the scanner is unreachable
Security Hardening	The checklist for a server about to face the internet: what to turn off, what to bind to loopback, what to rate-limit, what to log
Security Policy	Which versions receive fixes, and how to report a vulnerability privately

3. Operate it

Page	What it answers
Monitoring and Health	The three things worth doing first, then the Dashboard, the logs, the Prometheus endpoint, the health probes and the OpenTelemetry exporters
Backup and Restore	What a backup does and does not contain, scheduling one, the verified-restore check that runs on every backup by default, and restoring for real
Troubleshooting	Symptom by symptom, from "I cannot receive mail from outside" to "the server will not start", plus what the server actually said and what it meant
Diagnosing Stalled Mail	The case where nothing is broken and nothing moves: how the queue works, the retry schedule, and the log line that names the cause
Upgrading hMailServer	The upgrade procedure, the cost of each step, and the decision tree for which path you are on
Upgrading Guide	The mechanism underneath that procedure: what the database upgrade actually does, and why this is the one operation that can cost mail rather than time
Migrating the Database Backend	Moving between SQL Server Compact, SQL Server, MySQL/MariaDB and PostgreSQL. There is no migration tool and none is needed: it is back up, repoint, restore
High Availability Runbook	The supported active/passive topology, the health check that drives failover, and why the server deliberately contains no clustering code
Warm Standby	A second machine ready to take over: what must be replicated, what must not be running, and the DPAPI-protected passwords that do not travel
Runbooks Digest	Every runbook in the repository, what it covers, and where each of its claims was checked against the code — including the places the document and the code disagree

4. Extend it

Page	What it answers
Rules and Sieve	Two independent filtering systems, both running during delivery: server and account rules, and Sieve scripts managed over ManageSieve
Aliases Lists and Public Folders	Aliases, distribution lists with moderation and bounce handling, and public folders shared across accounts
Routes and Relays	Smart hosts, per-domain routes, and which hosts may relay through you — the setting most often got wrong in a way that ends on a blocklist
The COM API and Scripting	The COM object model, and the event scripts that run inside delivery so you can change what happens to a message
The REST API	The HTTP API and the self-service portal as an administrator meets them: turning the listener on, credentials, and what the routes are for
APIs Reference	The exhaustive version: four HTTP listeners all off by default, 65 REST routes with authentication and source lines, the web services listener, the metrics listener, and the COM object model

5. Contribute to it

Page	What it answers
Project Handbook	Building each component, running the suite, the checks a change must pass, and cutting a release — the whole project in one page
Architecture	A map of the codebase for someone about to change it: where a change goes, and the constraints that have already caused bugs here
Contributing	The short build, the DCO sign-off, and the checks a pull request has to pass
Release Process	The ordered, gated release procedure. Every rule in it exists because breaking it cost a release cycle or nearly shipped a defect
Governance	Who decides what, described as the project actually runs today rather than as an aspiration
Assurance Case	What the project claims about its own security, the argument and evidence for each claim, and what it deliberately does not claim
Regression Test Environment	What a machine must have to run the 2,127-test suite, which does not mock the server but drives a real one over SMTP, IMAP, POP3 and COM
Fuzzing	The parser fuzzing harness, and why a parser bug in this process is a mail outage rather than a failed request
Regulatory Scope	The dated, reviewable position on whether the Cyber Resilience Act and the revised Product Liability Directive place obligations on this project
Third-Party Binaries	The 40 committed binary files, what each one is and where it came from, and the CI job that fails the build when the record and the tree disagree

Look it up

Page	What it answers
Settings Reference	Every key of hMailServer.INI as the server reads it: 238 in [Settings] alone, each with its default, the code that consumes it, and whether it takes effect live or at restart
Settings Overview	The smaller set of settings the manual explains, with worked examples
Capabilities and Configuration	Every SMTP, IMAP, POP3 and ManageSieve keyword the server advertises today, checked against the code that emits it
Control Panel Reference	All 55 Control Panel pages and their dialogs, field by field, with the setting or COM property behind each one
Control Panel Pages	The same tree as the manual described it, page by page, with the screenshots
Ports Reference	Every socket the server can open and every socket it can open towards something else, and which of the two places configures it
[[Changes-Since-6210	Changes-Since-6210]]
[[Version-History-to-6210	Version-History-to-6210]]
Glossary	Each term: what it means, what it means here, and the Control Panel page, setting or wiki page to go to next

About this wiki

Twenty-six of the pages here began as chapters of the 6.2.10 manual and were corrected for 6.2.24 and again for 6.2.28; each one says so at the top. The reference pages headed Settings Reference, Capabilities and Configuration, Control Panel Reference, APIs Reference and Changes Since 6.2.10 were produced by reading the code and every release note, and carry file and line references so a claim can be checked. The rest are copies of documents kept in the repository, and Runbooks Digest names the file behind each. Found an error? Open an issue naming the page.