Let's Encrypt certificates are automatic: the built-in ACME v2 client

Written for 6.3.4. hMailServer 6.3.7 (17 October 2026) fixes the ACME HTTP-01 challenge responder, which served one connection at a time, so that idle clients could make a certificate's issuance or renewal fail in every earlier version (work item 97): it now serves up to 64 connections at once and closes one past that, though a client that holds 64 idle connections open through a whole validation can still make it fail. In 6.3.7's Control Panel the SSL certificates page is TLS certificates, and Ctrl+K takes the old title to it. See the 6.3.7 announcement. hMailServer 6.3.8 (2 November 2026) no longer leaves a host added to AcmeDomains waiting for the renewal (work item 98): a certificate that does not name every host on the list is due at once, a save of the list in the running server starts the check (a value hmailserver --set-setting stores is read at the next reinitialise or start), and GET /api/v1/acme, POST /api/v1/acme/run and the Control Deck's Certificates page give the certificate's state and ask for a check, the CA's rate limits kept. Where the list holds a host the certificate lacks, the first check after the upgrade orders a certificate for every host on it, and a host the CA cannot validate fails the whole order, at most three times an hour, and holds the renewal for the other hosts: take such a host off the list before upgrading. A wildcard, an IP address or another name no certificate can carry is left out of the check and the order and named in the application log. An IP range of your own that allows some addresses none of SMTP, POP3 and IMAP now closes the web services listener to them, and with it ACME's http-01 validation where that listener answers it, so check that the certificate authority does not come from one; and on Windows an AcmeCertificateDirectory whose path holds characters outside ASCII may be refused with HM7536, and then the client reads and writes nothing there and orders no certificate: give it, and the folders above it, an ASCII name before upgrading. See the 6.3.8 announcement.

hMailServer has an ACME v2 client built in (RFC 8555). It obtains a free certificate, installs it, assigns it to your TLS ports, renews it before expiry and reloads it. No restart, no scheduled task, no external client.

Configure it under TLS & certificates → Certificates (ACME), over REST with PUT /api/v1/settings/ini/{name}, or on Linux with sudo hmailserver --set-setting NAME=VALUE. Since 6.3.4 these are database settings, not lines to edit in hMailServer.INI: a line edited there is named in the error log (HM5804) and not used, and is put back where the service may write the file. The values:

AcmeEnabled=1
[email protected]
AcmeDomains=mail.yourcompany.com,mta-sts.yourcompany.com,autoconfig.yourcompany.com
AcmeHttpPort=80
AcmeReuseKey=1

AcmeEnabled ships as 0, and a change to it takes effect at a reinitialise (Apply now), not at the save. AcmeDirectoryUrl defaults to https://acme-v02.api.letsencrypt.org/directory.

Two requirements. Port 80 must be reachable from the internet, because that is how the http-01 challenge proves you control the name. Every name in AcmeDomains must already resolve to this server before you switch it on. If you also host MTA-STS or client autoconfiguration, put mta-sts.<domain>, autoconfig.<domain> and autodiscover.<domain> in AcmeDomains so one certificate covers them.

After issuance. The server creates or updates a certificate record named ACME (automatic) and assigns it to every TLS-enabled listener that has none of its own, and since 6.3.4 to every listener still holding the self-signed certificate a new installation is given, logging each assignment. A listener the assignment could not be saved for is reported as a High 6100 rather than logged as a success, because a port left without a certificate accepts no TLS at all. That is the error to alert on.

Renewal. The renewal window is two thirds of the certificate lifetime, plus ARI. That is why there is nothing left to schedule. Files live in Data\ACME on Windows and /var/lib/hmailserver/ACME/ on Linux: the account key, fullchain.pem and privkey.pem. Back that directory up with the rest of Data\. If a restore misses it the client re-issues, but the new key invalidates any TLSA records you have published.

Leave AcmeReuseKey=1. Keeping the same private key across renewals is what keeps published TLSA records valid.

Linux. Port 80 works without root. CAP_NET_BIND_SERVICE on the unit is what allows the bind. The default certificate directory is <DataFolder>/ACME, which is inside ReadWritePaths. Point AcmeCertificateDirectory elsewhere and you must add that path to ReadWritePaths with a drop-in, or issuance fails on a read-only filesystem.

If it never worked for you. The built-in client had never once succeeded against real Let's Encrypt until 6.2.24 (GitHub issue 34). Boulder pretty-prints its JSON and the challenge locator searched for the compact spelling. 6.2.25 then fixed issuance and renewal ending the process (GitHub issue 93). If you gave up on this on an older build, it is worth another look.

Another CA. Leave AcmeEnabled=0, add the PEM certificate and key under TLS & certificates → SSL certificates, then assign it to ports under Connections & protocols → TCP/IP ports. On Linux, an external client that replaces the PEM files in place needs POST /api/v1/server/reinitialize or a restart before the new files are served.

Chapter 9, encryption and certificates: https://www.progressiverobot.com/hmailserver-documentation/#9-encryption-and-certificates
Report problems: https://gitlab.com/hmailserver/hmailserver, or without a GitLab account by email to the project's Service Desk address, contact-project+hmailserver-hmailserver-86730559-issue-@incoming.gitlab.com