How email works, and what hMailServer is and is not

[Progressiverobot]

Written for 6.3.4. hMailServer 6.3.6 (6 October 2026) carries Linux packages for x86-64 and AArch64 and one for each of ten distribution releases, both AppImages, an ARM64 Windows installer (a preview) and the first container image. See the 6.3.6 announcement. hMailServer 6.3.7 (17 October 2026) is a security release: mail from outside whose From names a domain hosted here is no longer signed with that domain's DKIM key, an authenticated submission is signed as another hosted domain only when its account may send as the address its From names, and a forward of outside mail is given an envelope sender in the forwarding domain's organisation only when the message passed DMARC for it on arrival. See the 6.3.7 announcement. hMailServer 6.3.8 (2 November 2026), the current release, is a security release: it fixes vulnerabilities the project found in its own code, so upgrade every server running 6.3.7 or earlier. See the 6.3.8 announcement.

This tutorial is for someone who has not run a mail server before. It follows a message from one person to another, shows where hMailServer sits on that journey, and says what the software does and does not do. The one thing to know first: port 25 has no password, and it has to be that way. Any server on the internet may connect to your port 25 and offer you mail for your own domains, or nobody could write to you. Your own users send through a different door, port 587, which requires a login. Most of what follows is about keeping those two doors apart.

What hMailServer is

hMailServer is a mail server: the software that owns an email domain. When someone sends a message to [email protected], their mail server looks up where yourcompany.com receives mail and delivers it to whatever is listening there. If you run hMailServer, that is your machine. Progressive Robot Ltd forked hMailServer in 2026 and maintains the hMailServer 6 line; the current release is 6.3.8, of 2 November 2026.

Job	Protocol	What it means
Accept mail from the world	SMTP	Other mail servers connect and hand you messages for your users
Let your users read mail	IMAP and POP3	Outlook, Thunderbird, Apple Mail and phones connect to fetch messages
Let your users send mail	SMTP submission	Your users hand you messages and you deliver them onward

Where it sits, and what is not yours

Running your own mail server means owning the middle of three boxes. DNS is your registrar's, and the mail clients are your users'. The wiki puts it plainly: almost every problem people describe as "hMailServer is broken" turns out to be in one of the two boxes it does not own.

You provide	hMailServer provides
A machine reachable from the internet	The SMTP, IMAP and POP3 servers, and the whole delivery pipeline
A host name with an A record, and an MX record pointing at it	The MTA-STS policy derived from that MX, and a live check of every record
A PTR record, which only your ISP can set	Nothing can substitute for it
SPF, DKIM and DMARC records in your zone	The DKIM key generation with a copyable record, the signing, and the inbound evaluation of everyone else's
Port 25 reachable inbound, and outbound (many consumer ISPs block outbound 25)	Nothing can work around a blocked port; a smart host is the usual answer
A certificate, or nothing, and let ACME get one	Built-in Let's Encrypt issuance and hourly renewal
Somebody who will read a log occasionally	The logs, the diagnostics, the message trace and the metrics to read

A message's journey

You send mail to [email protected]. This is what happens:

1. Your mail client submits the message to your hMailServer on port 587. You log in first.
2. hMailServer answers 250 Queued.
3. It asks DNS who receives mail for example.com. The MX record answers: mail.example.com.
4. It looks up the A and AAAA records for that host, plus TLSA and the MTA-STS policy.
5. It delivers the message by SMTP on port 25: no login, TLS if offered.
6. The recipient's server answers 250 OK and stores the message in Alice's mailbox.
7. Alice's mail client reads it over IMAP.

An open relay is the thing to avoid. Never let an unauthenticated stranger send mail through you to the outside world. The wiki's warning is that it will get your server blacklisted within hours. hMailServer refuses this by default.

A note on ports. A fresh install seeds ports 25, 587, 110 and 143. The TLS ports 465, 993 and 995 exist only after you create them on the TCP/IP ports page.

A submission, and the checks in the order the server runs them

The order matters, because it decides when a sender is told no: before the message body is transferred, or after.

Stage	What is checked	Reply when it fails
Any command	On a STARTTLS required port, everything but NOOP, EHLO, STARTTLS and QUIT	530 Must issue STARTTLS first.
MAIL FROM	Free disk space: MinimumFreeDiskSpaceMB, default 100	452 4.3.1 Insufficient system storage
MAIL FROM	Send-As, only when SmtpAuthenticatedSenderCheck=1 (default 0)	550 5.7.1 Sender address rejected
MAIL FROM	Per-IP rate: MaxSubmissionsPerIPPerMinute (default 0, unlimited)	421 Too many messages from your IP address
MAIL FROM	Declared SIZE against the domain's maximum message size (default 20480 KB)	552 5.3.4 Message size exceeds fixed maximum message size
RCPT TO	Is the address deliverable at all?	550 Unknown user, or 451 4.3.2 Unable to verify the recipient at the moment
RCPT TO	Mailbox full	452 4.2.2
RCPT TO	Relay permission for this IP range	550 Delivery is not allowed to this address.
RCPT TO	Authentication required and not supplied	530 SMTP authentication is required.
RCPT TO	Greylisting, when it is on (default off)	451 Please try again later.
end of data	Actual size, bare LF check, post-transmission spam tests	552 5.3.4, 554 5.6.0 Rejected - Message containing bare LF's, 554 5.7.1

4xx and 5xx. A 4xx reply always means "come back later", while a 5xx means "never". The difference decides whether a legitimate sender's message waits in their queue or is destroyed, which is why a full mailbox is 452 and not 550.

Refusing early. Every check at MAIL FROM and RCPT TO happens before a single byte of the message crosses the wire. Refusing early costs the sender nothing, and it generates no bounce to an address a spammer only claimed to be.

The timing in the last reply is real. A submission ends with a line such as 250 2.0.0 Queued (0.412 seconds): the server times the accept-and-save stage and reports it. A number that climbs into whole seconds is the first sign of a slow spam test, a stalled virus scanner or a saturated work queue.

Since 6.3.4 the same session has more places to say no, each of them off until an administrator sets it: country blocking, a domain white and black list, restricted delivery, mail flow rules and others. One thing differs without a switch, and only on a new installation, not an upgrade: the Internet IP range requires TLS for authentication, so from another machine AUTH is not offered before STARTTLS.

Who may send through you

This is the decision that separates a mail server from an open relay, and hMailServer makes it per IP range. Mail from other domains to yours is taken on port 25 without a password, or nobody could write to you. From the Internet range, mail that gives one of your own domains as its sender needs a login, whoever it is for, and relaying from one remote address to another is allowed on both shipped ranges only with authentication: a stranger who has not logged in is answered 530 SMTP authentication is required. A range that allows relaying without authentication must never exist (the Control Panel's status page warns of one as an open relay). Ranges are matched by priority, highest first, so a narrow range for your own network can sit in front of the broad Internet range; IP ranges, auto-ban, lockout and the rest has the whole grid and the shipped values.

After "250 Queued": the delivery pipeline

Acceptance and delivery are separate. The 250 means the message is on disk and in the database; delivery happens on the delivery threads afterwards, in this order:

1. The OnDeliveryStart script event.
2. Virus scanning.
3. Global rules.
4. The OnDeliverMessage script event.
5. DKIM signing, then mirroring, each on the first attempt only.
6. Local delivery: account rules, Sieve, forwarding, distribution lists, public folders.
7. External delivery for any recipient outside this server: routes or an MX lookup, MTA-STS, DANE, TLS, then SMTP.

A temporary failure is rescheduled: 4 tries, 60 minutes apart by default. A permanent failure, or retries exhausted, produces a delivery status notification to the sender.

Where the filters sit

Anti-spam runs in two phases, before and after the message is transmitted, and a test's phase is fixed by the test. Two thresholds decide what a score means: mark (default 5) adds spam headers, and delete (default 20) refuses the message, or quarantines it when the quarantine is on.

On a fresh install almost every test is off. zen.spamhaus.org, bl.spamcop.net and multi.surbl.org are seeded but inactive; the HELO, PTR, MX and SPF tests are off; SpamAssassin is off; greylisting is off. DMARC is on (ASDMARCEnabled 1), and it evaluates SPF and DKIM itself for its own purposes. Anti-spam does not run at all for an authenticated session, for a whitelisted sender, or for an IP range with spam protection switched off.

Reading mail back: IMAP or POP3

	IMAP	POP3
Mail lives	on the server	on one device
Folders	yes, and shared/public folders too	INBOX only
Read/unread, flags	shared across devices	per device
New-mail notification	IDLE pushes it	polling only
Server-side search	yes	no
Concurrent sessions	many	one at a time; a second gets -ERR [IN-USE]
Default ports here	143, and 993 once you create it	110, and 995 once you create it

The wiki's advice is short: use IMAP.

The three records that make mail arrive

• SPF: a list of the servers allowed to send mail for your domain.
• DKIM: a cryptographic signature proving the message really came from you and was not altered.
• DMARC: a policy saying what to do when SPF and DKIM disagree, and where to send reports.

Without them your mail will go to spam. The wiki calls this the most common reason a new mail server "doesn't work". Note the asymmetry: hMailServer signs your outgoing mail with DKIM as soon as you configure a key, but checking SPF on incoming mail is off by default. Being trusted by the servers you send to has the detail.

What hMailServer is not

• It was not a webmail client; since 6.3.2 it is one. The page at /portal on the REST listener became a mail client in 6.3.2, and a separate webmail such as Roundcube is no longer needed, though it still works over IMAP. Of 6.3.4's paging of a folder of a hundred thousand messages, the wiki says: built, and not yet measured. See The webmail portal at /portal.
• It is not a spam filter you can point at someone else's mail. It filters mail it receives, for domains it hosts.
• It is not Exchange. There is no ActiveSync, no MAPI and no Teams integration, so Outlook connects over IMAP and SMTP like any other client. Since 6.3.4 it carries the pieces of groupware that ride on standards, such as calendars over CalDAV.

Who should run it: a small business that wants its own mail on its own server; a developer who needs a real SMTP/IMAP endpoint for testing; a hosting provider running mail for many domains. Who should not: if nobody in your organisation is comfortable editing DNS records and watching a log file occasionally, a hosted mailbox provider will serve you better.

What you run it on

	Windows	Linux
Platform	64-bit Windows 10 1607 / Server 2016 or later	Since 6.3.0. 6.3.4's packages are x86-64 only: a .deb for Ubuntu 26.04 and 24.04, an .rpm for Fedora 43 and 44 and Enterprise Linux 10
Administration	The Control Panel, the COM API, the Control Deck and the REST API	The Control Deck and the REST API. The Control Panel and the COM API are Windows-only
Event scripts	VBScript or JScript	JavaScript, since 6.3.4

The AArch64 packages and the AppImage were last published with 6.3.3. 6.3.4 is installed by hand; no live update installs it. hMailServer on Linux: what you get and what you do not and First install on Linux go further.

"Additive and off by default"

The design rule is that an existing installation upgrades without behaving differently until you turn something on.

Category	State on a fresh install
Optional listeners: the REST API and /portal, web services, metrics, ManageSieve	Off. Each stays inert until its port setting is non-zero
Optional features: quarantine, message trace, full-text index, archive	Off
Outbound transport security: MTA-STS, DANE, DNSSEC validation	On (MtaStsEnabled, DaneEnforcementEnabled, DnssecValidationEnabled). Each can be switched off
A new installation of 6.3.4, not an upgrade	A self-signed certificate, STARTTLS offered on 25, 587, 110 and 143, TLS required for authentication from the Internet range: see Hardening a public mail server

Since 6.3.4 the database is the settings store: a [Settings] line edited in hMailServer.ini is ignored in favour of the stored value, and put back where the service can write the file.

Words you will meet

Term	Meaning
MTA	Mail Transfer Agent: a mail server that accepts and forwards messages. hMailServer is one
MSA	Message Submission Agent: the server your own users hand mail to, normally on port 587, normally with authentication
MUA	Mail User Agent: the mail client
Relay	Accepting a message for a domain you do not host and passing it on
Smart host	Another server you send all your outbound mail through, often your ISP's
STARTTLS	Upgrading a plaintext connection to an encrypted one, in-band
Implicit TLS	TLS from the first byte, no upgrade step: ports 465, 993, 995
Envelope vs header	The MAIL FROM/RCPT TO addresses the servers use, versus the From:/To: a person reads. They need not match
Deferral	Holding a message for a later attempt after a temporary failure
Backscatter	Bounces sent to a forged sender address
MX record	The DNS record saying which server receives a domain's mail
PTR record	Reverse DNS: maps an IP back to a host name

Where to read more

• Wiki: How Email Works, What hMailServer Is and Is Not and the Glossary.
• The public documentation: chapter 1, chapter 2 and the glossary.
• On this forum: Read this before you post and Where to post what; for the next steps, Your first domain and mailbox, and the DNS records your domain needs, Connecting a mail client, The anti-spam stack end to end and Every port hMailServer listens on.