Your first domain and mailbox, and the DNS records your domain needs

Progressiverobot

This topic takes a freshly installed hMailServer 6.3.4 to its first working mailbox, proves it locally, and then lists the DNS records without which its mail either does not arrive or is filed as spam. The one thing to know first: the domain's Postmaster address box is the catch-all, not the postmaster@ mailbox the email standards ask for. Create postmaster@ as an account, and leave that box empty unless you want every misaddressed message accepted and stored. The paths below are the Windows Control Panel's; on Linux, which has no Control Panel, the same is done in the Control Deck or over the REST API.

If you are learning, make the sample domain first (since 6.3.4)

One button, on the Control Panel's Welcome page and on the Control Deck's Checklist view, or one command (hmctl sample-domain create, hmailserver --sample-domain create on Linux, POST /api/v1/setup/sample-domain) makes a throwaway example.test: three mailboxes, a distribution list of the three, one rule and eight delivered messages. The same button, or ... remove, takes it away and says what it removed; a domain called example.test that it did not make is never touched.

All three mailboxes sign in with one password, which the server mints when it makes the sample: twenty characters of Crockford base32, grouped in fives. It is shown once, in the answer to the call that made the sample, and is stored nowhere, so write it down; if you lose it, remove the sample and make it again. Older wiki text that speaks of "one documented password" describes an earlier version of the feature and is out of date. Remove the sample before the server takes real mail. Its mailboxes are ordinary accounts that can sign in and relay.

Add your domain

Go to Accounts & domains → Domains, type the name and press Add domain, then select it and press Properties. On Linux, use the Deck's Domains view, or:

curl -u Administrator -H "Content-Type: application/json" \
     -d '{"name":"example.com","active":true}' \
     http://127.0.0.1:8045/api/v1/domains

postmaster is optional in that body and is left out here, because it is the same catch-all field. The call answers 400 if the name is not a valid domain name and 409 if it already exists. Since 6.3.4 the Control Panel's domain editor has fourteen tabs; the seven that 6.3.4 added are each off, or empty, until set. The fields that matter on the first day:

Tab	Field	Default	What happens when it is wrong
General	Domain enabled	ticked	Unticked: every `RCPT TO` is answered `550 Domain has been disabled.`
General	Domain name		The part after the `@`. Setting it to the host name (`mail.example.com`) is the classic first-day mistake
General	Postmaster address	empty	The catch-all. Set: no address in the domain can be refused. Empty: unknown recipients get `550 Unknown user`
Limits	Maximum message size (KB)	`0`	`0` falls back to the server-wide `maxmessagesize`, seeded at 20480 KB
Limits	Enable plus addressing	off, `+`	Off: `alice+invoices@` is an unknown recipient
Relay	Relay host	empty	Where mail from this domain leaves through. This is not a route
DKIM	Enable signing	off	Enabling before the DNS record is live makes every message fail DKIM at the receiver

In RecipientParser::CheckDeliveryPossibility, an address that matches no account, alias, distribution list or route falls through to the postmaster address and the resolution restarts with it. That is why the box is a catch-all.

Add a mailbox

Select the domain, type the address and a password under the account list, and press Create account; then Edit for the full editor.

Field	Value to use	Notes
Password	Press Generate strong password	16 characters from a cryptographic RNG, shown once and copied to the clipboard
Administration level	Normal user	Server administrator can manage everything. Give it only to yourself
Quota (MB)	`0` for unlimited
Account enabled	ticked	Unticked: `550 Account is not active.` at `RCPT TO`

On Linux, make the account on the Control Deck or with POST /api/v1/domains/{domain}/accounts. Create at least [email protected] and your own mailbox. A full mailbox is refused during the SMTP conversation, not bounced: with RejectFullMailboxAtRcpt on, as it is by default, RCPT TO is answered 452 4.2.2 Mailbox is full., a temporary refusal, so the sending server holds the message and no backscatter is sent.

Since 6.3.4, accounts can be imported from a CSV file over REST, with hmctl and with the PowerShell module, with a dry run that changes nothing; and an identity provider can make and remove them over SCIM. Three things about an account are set only on the Control Deck and over REST, not in the Control Panel: its kind (a person, a room or equipment), encryption at rest, and a webhook route.

How an address is resolved

Every RCPT TO is answered by one function, in a fixed order that ends at the domain's postmaster address; the full order, with domain aliases, plus addressing and the webhook route, is in Aliases, distribution lists and public folders. What it means on the first day:

Question	Answer
Why did mail to a mistyped address get delivered?	The domain has a postmaster address, so it fell through to the catch-all
Why does `alice+anything@` not work?	Plus addressing is off by default and is per domain
Why does an alias to an external address still count as local?	Only at the first hop, so that it is treated as inbound mail and not as relaying

Test it locally, before touching DNS

The test below works because a fresh database's My computer IP range lets the server itself, on 127.0.0.1, send as one of its own domains without a password, while anyone may send you mail and nobody may relay through you without logging in. A refused direction is 550 Delivery is not allowed to this address.; one that needs authentication is 530 SMTP authentication is required. The two seeded ranges and what each allows are in IP ranges, auto-ban, lockout and sending limits.

Send-MailMessage -SmtpServer localhost -Port 25 `
   -From "[email protected]" -To "[email protected]" `
   -Subject "First test" -Body "If you can read this, hMailServer is working."

Or by hand with telnet localhost 25. The replies worth recognising:

Line	What it tells you
`250-SIZE 20971520`	The server-wide `maxmessagesize`, 20480 KB, in bytes
`250-STARTTLS`	Present only when the port's connection security is STARTTLS optional or required
`250 AUTH …`	Absent when the port requires TLS, or the connecting range requires TLS when authenticating
`250 2.0.0 Queued (0.016 seconds)`	The message is on disk and in the database
`250 2.0.0 Queued for delivery`	Not the same reply: the message was quarantined

Then check Monitoring & troubleshooting → Delivery queue, which should be empty, and look on disk: a delivered message is one file, C:\Program Files\hMailServer\Data\yourcompany.com\you\a3\{a3f01e6c-....eml}. Its first Received header reads with ESMTP, and with ESMTPSA for an authenticated submission over TLS.

The DNS records your domain needs

Do them in this order. Replace yourcompany.com and 203.0.113.10 with your own.

Record	Example	Without it
A / AAAA	`mail.yourcompany.com. IN A 203.0.113.10`	Nothing resolves; the MX points at nothing
MX	`yourcompany.com. IN MX 10 mail.yourcompany.com.`	Inbound mail bounces as "no mail server for this domain"
PTR	`10.113.0.203.in-addr.arpa. IN PTR mail.yourcompany.com.`	Google and Microsoft refuse or spam-folder outbound mail
SPF	`yourcompany.com. IN TXT "v=spf1 mx a:mail.yourcompany.com ~all"`	Anybody can forge your domain; DMARC cannot pass on the SPF side
DKIM	`dkim._domainkey.yourcompany.com. IN TXT "v=DKIM1; k=rsa; p=MIIBIjANBgkq..."`	Forwarded mail fails everything, because forwarding breaks SPF
DMARC	`_dmarc.yourcompany.com. IN TXT "v=DMARC1; p=none; rua=mailto:[email protected]"`	No policy and no reports

A / AAAA and MX. Add an AAAA only if the machine has a public IPv6 address that answers. An MX must point at a host name, never an IP address, and that name must not be a CNAME. The MX name is what MTA-STS matches, what TLSA records hang off, and what the certificate on port 25 should be issued for.

PTR. Only your ISP or hosting provider can set it. It should name the same host as your HELO/EHLO, which hMailServer takes from Connections & protocols → Protocols → SMTP, Host name (HELO/EHLO greeting), falling back to the Windows computer name when blank. The Control Panel's DNS records page does not check it, and says so.

SPF. Start with ~all; move to -all once the DMARC reports have shown you every system that sends as you. Publish exactly one SPF record per name: two beginning v=spf1 is a permanent error at every receiver. RFC 7208 caps the DNS-querying mechanisms at ten. In the other direction, checking SPF on incoming mail as a scored test is off by default (usespf is seeded 0), but DMARC checking is on by default and evaluates SPF and DKIM itself.

DKIM. On the domain's DKIM tab click Generate key pair…: it creates an RSA-2048 key, saves the private key and shows the exact record, with a Copy DNS value button. dkim is the default selector. Switching signing on is gated on the published record matching. Ed25519 is supported too, with a key you supply. Since 6.3.4 a rotation policy per domain generates the new key under a dated selector (s20260915), checks the record every fifteen minutes and switches signing only once it has carried that key for a propagation period. It never edits DNS, and it is off until switched on.

DMARC. Start with p=none, read the reports for a few weeks, then tighten to p=quarantine and p=reject. Do not start at p=reject. The DNS records page pre-fills rua= with the domain's postmaster address and omits the tag when there is none. Since 6.3.4, name that mailbox as the domain's report mailbox and the server parses the DMARC and TLS-RPT reports that arrive there and charts them on the Control Deck's DMARC page. Nothing read there acts on any mail.

Optional hardening, at any point afterwards:

Record	Name	Notes
MTA-STS	`_mta-sts.yourcompany.com. IN TXT "v=STSv1; id=20260908120000"`	hMailServer serves the policy itself once `WebServicesHttpsPort` is set and the listener has a certificate for `mta-sts.yourcompany.com`; `MtaStsPolicyMode` defaults to `enforce`, so set it to `testing` to start
TLS-RPT	`_smtp._tls.yourcompany.com. IN TXT "v=TLSRPTv1; rua=mailto:[email protected]"`	Asks other servers to tell you when TLS to you failed
TLSA	`_25._tcp.mail.yourcompany.com. IN TLSA 3 1 1 <sha256 of the certificate public key>`	Only meaningful if your zone is DNSSEC-signed. Re-publish before you rotate a certificate, never after
CNAME	`autoconfig`, `autodiscover`, `mta-sts` → `mail.yourcompany.com.`	For client autoconfiguration and the policy host
A / AAAA / CNAME	`openpgpkey.yourcompany.com`	Since 6.3.4, only if you publish OpenPGP keys

BIMI is read, not published: since 6.3.4 the webmail shows a sender's logo, but this server publishes no BIMI record for your domains.

Checking your work

Give DNS an hour to propagate. Monitoring & troubleshooting → DNS records lists, per domain, the exact SPF, DKIM, DMARC, MTA-STS and TLS-RPT records to publish, with a Check button per record:

Verdict	What to do
Not published	Publish it
Published but different	Compare the two; the page shows what is there
Published and correct	Nothing
Lookup failed	A resolver or network problem, not a DNS-content one. Retry

On Linux the Control Deck has a DNS records view. On either platform the first-hour checklist (since 6.3.4) judges the spf, dkim and dmarc items itself, for the first twenty active domains. From a command line:

Resolve-DnsName yourcompany.com -Type MX
Resolve-DnsName yourcompany.com -Type TXT
Resolve-DnsName dkim._domainkey.yourcompany.com -Type TXT
Resolve-DnsName _dmarc.yourcompany.com -Type TXT
Resolve-DnsName 10.113.0.203.in-addr.arpa -Type PTR

Being trusted by the servers you send to takes deliverability further.

The ports your users will need

The create scripts seed four listeners, SMTP 25 and 587, POP3 110 and IMAP 143, with no encryption. Since 6.3.4 a new installation sets all four to STARTTLS optional with the self-signed certificate and requires TLS for authentication from the Internet IP range; an upgraded server is left as it was (Hardening a public mail server). Ports 465, 993 and 995 are not created for you: add them on Connections & protocols → TCP/IP ports once you have a certificate.

A TLS port with no certificate selected does not start (HM5113, Error initializing SSL. Certificate not set.); a port already in use is HM4316. Which connection security each port should have, and why STARTTLS optional belongs on port 25 alone, is in Connecting a mail client; which ports to open in the firewall is in Every port hMailServer listens on.

Before you tell anyone the address

postmaster@ exists as a real account.
MX, SPF, DKIM and DMARC are published and verified.
A certificate is installed and the client ports created: Let's Encrypt certificates are automatic.
The administrator password is a PBKDF2 one. 6.3.4's installer writes it so; the wiki's checklist item about changing it from "the installer's MD5" describes 6.3.3 and earlier.
A backup that you have restored once.

What it does not do, and where to read more

Nothing here publishes a DNS record for you: the Control Panel builds the text and checks it, and the DKIM rotation never edits DNS. The PTR record is your provider's to set. More on the records above: DKIM rotation, DMARC and TLS reports, and Requiring TLS for MTA-STS, TLS-RPT and DANE. The webmail and browser administration are separate topics: The webmail portal at /portal and The Control Deck.

Sources: the wiki's Your First Domain and Mailbox, DNS for Your Domain and Ports Reference; SampleDomain.md and SetupChecklist.md; and chapters 6, 8 and 22 of the public documentation.