History / The REST API

The wiki describes the tree after 6.3.3 as it lands on master: the settings store, the audit trail and alerts, what a domain does to a message, remote-domain policy, a backup that carries everything, and the rest of three batches Twenty-seven pages, each written from the code at 3233b0cc4 and then checked sentence by sentence against it by a second reader: 166 claims verified, 23 corrected before this commit. Everything the tree holds that no release has is labelled as in the tree after 6.3.3 and not yet released, and the next release is called that rather than given a number. The changes page carries the four schema steps 6042 to 6045 in section 2, the second and third batches in section 4e beside the first, the gate for 3233b0cc4 (2,410 tests, 2,402 passed, none failed, 8 skipped; the Linux figures are a placeholder until that run lands), and in section 5 the changes an upgrade makes with no switch - above all that the database is the settings store, that an edit to [Settings] in hMailServer.ini is undone at the next start and reported as HM5804, what to do instead, and that the password pepper stays in the file and out of every backup, so a restore onto new hardware needs it brought along. Fourteen pages that told a reader to edit the file now say how the same setting is changed once the store lands, and what an edit to the file does then; the settings reference says the table of INI keys is closed. The feature pages cover the backup that carries every per-account store, the audit trail and alerts with what each does not yet record or raise, syslog export, per-domain reports, remote-domain policy and mandatory TLS, SPF as RFC 7208, hmctl's configuration document, the tours, and the REST routes counted at the commit rather than guessed at. The checking found things the tree itself gets wrong, which are recorded for the next batch rather than papered over here: hmctl's configuration document has an empty ini section because it reads a route that answers names only; the packaged Linux ini's RestApiPort=0 is adopted into the store at first start, so the packaging README's edit-the-file way of turning the REST listener on no longer works; the OpenAPI text for the ini routes and the note the server writes into hMailServer.ini still describe the file as the store; and five repository documents say what their wiki copies said before this commit.

chrisholloway5 committed Sep 15, 2026

A page for the two command-line clients, which are in the tree since 15 September 2026 and in no release yet. hmctl is one Python file with nothing but the standard library behind it, which the .deb and the .rpm install as /usr/bin/hmctl, and the HmailServer PowerShell module beside it is the same vocabulary in PowerShell's grammar; both speak the REST API rather than COM, so both work against a Windows server, a Linux server or one on another machine. The page is the repository document copied here as the fuzzing page is: the verbs by resource, the credentials and why --insecure is refused anywhere but the loopback, accounts imported from and exported to a CSV file with a dry run and the rule that an address which already exists is left alone rather than overwritten, and what neither client does - no message store, no backups of its own, no administrator password. The sidebar lists it under "Extend it" beside the two APIs, the REST API page points at it in its first paragraph, and the landing page's index and its "what do you want to do" table carry it.

chrisholloway5 committed Sep 15, 2026

Four pages catch up with what is in the tree since 6.3.3 and with what shipped in it. The client page gains a CalDAV section beside the CardDAV one, written the way the CardDAV section is: the same listener, the same discovery and the same credentials, one calendar per account at /dav/calendars/<address>/calendar/ made the first time it is asked for, VEVENT and VTODO in the one collection so a phone's calendar and its reminders are the same thing, a repeating event expanded by the server across daylight saving in any of the 592 zone names the new iCalendar module knows, and calendar-query, multiget and sync-collection with ETags. It says what is not there too, because a calendar that silently drops an invitation is worse than one that never offered: no iMIP, no free-busy, no per-calendar time zone, no partial calendar-data, and no time-range filter on an alarm. The webmail paragraph loses a label that went stale the moment 6.3.3 was published - it said "6.3.3, unreleased" of what is now the current release - and gains the twelve features that followed it, each in the reader's terms rather than the roadmap's: the page installed as an app with its unread badge, contacts in and out, saved searches as folders, the reader's own time zone, undo on three more actions, the tracker notice counting what it kept out, swipe actions and snooze presets, three stars that every IMAP client sees as keywords, rows coloured by a rule, @mentions that add the person to the recipients, a formatted signature, and Report phishing beside Junk. The container page gains the two files people expect and this repository now ships. The Compose section says that the file is in the tree, that a workflow resolves it with docker compose config on every change - so it is a file known to parse rather than an example in a document - and how it differs from the page's own shortest-thing-that-starts version: the two passwords are Compose secrets read from files, and the REST certificate is mounted in. Then a Kubernetes section: a StatefulSet of one, because a message store is not something two pods may share, the three volumes as claim templates, the database pointed at and never bundled with the chart refusing to render without a host, the two passwords as a Secret the chart makes or an existing one it is pointed at, the REST listener needing a kubernetes.io/tls Secret because off loopback the server requires TLS, a LoadBalancer with externalTrafficPolicy Local so the server sees the client's address, and probes on port 25 as the image's own health check is. It ends with how the chart is proven, since neither Helm nor Docker is on the bench that gates the code: linted, rendered with a real install's values, and checked for its two refusals, on every change. The REST page gains wave J's routes with the unreleased label: the account groups as a resource (a listing, a create, a read, a rename, a delete, and the members beneath a group as their own small collection, because a membership is a pair and not a property of either side), a message copied into another folder of its account, and the rule-criterion probe that answers what the delivery path would decide without reading or writing anything. And the fuzzing page is re-copied from the repository document it declares as its source of truth, which now carries the nightly job: the three harnesses every night on a hosted runner, the corpus kept in the Actions cache under a key that carries the run id so it grows, and the crash, hang or violated invariant that fails the job and lands the reproducer as an artifact.

chrisholloway5 committed Sep 15, 2026

6.3.0 is published, so the pages that were waiting for it say so: Linux is released rather than "in the tree", the write surface has a release number, and the version that never existed is gone The Linux page opened with a banner saying the port was in the tree and not yet released, and that the first release to carry packages would be "the next one". That release is 6.3.0 and it went out on 10 September 2026, so the banner now points at it and the install commands name the packages that are actually on the release page rather than a version number nobody can download. Five places named 6.2.29. There is no such version and there never will be - the release after 6.2.28 is 6.3.0, and README.md already says why - so the two package filenames, the two "since 6.2.29" notes about relative directory values and the Installation paths diagnostic's label all move to 6.3.0. The API reference's route tables gained the write surface a day before the release but nothing in them said which release it belonged to, while the rows around them carried 6.2.27 and 6.2.28. A reader could reasonably have read the settings, rules and certificate routes as shipping in 6.2.27, which is half true and the misleading half: those routes could only be read then. Section 4 now says which routes arrived in 6.3.0 and why the method column is the one to read, and the scope note names the units the write surface was split into. The landing page's At a glance table was stale in five of its rows: the release and its build number, the platform (Windows only, when the whole point of 6.3 is that it is not), the administration surfaces, the suite's size and the wiki's own page count. The route count was stale in a way worth recording: it said 65, which matched neither the number of rows in the reference table nor the number of distinct paths at the commit it was written from, so it is now 82 routes over 68 paths, both countable from the page it points at. The Control Panel reference said "the latest, v6.2.28", and one thing under ControlPanel did move in 6.3.0: the sign-in box's user name is a literal again (#156), which is why a fresh installation in Chinese could not sign in. The page says so, with the twenty-one files that differ between the tags. The footer stamped 6.2.28 on all fifty-one pages.

chrisholloway5 committed Sep 10, 2026

The Control Deck writes: the API Reference's page section says what the ten views do, how the page signs in for a session instead of keeping the administrator password, and why a 401 no longer opens the browser's own credential box over it The REST page's session section is named for both browser sessions now, the portal's and the Deck's.

chrisholloway5 committed Sep 9, 2026

The REST API writes: the route tables on the REST and API Reference pages carry the settings groups, the rules, the routes, the aliases, the account update, the certificates and listeners and the restart in place, with what each refuses and who may call it The Installing on Linux page's suite row and the Regression Test Environment page's "On Linux" section say what the write surface changed for the Linux run: 278 of 319 pass where 233 did, and what still skips is a COM-only call or the suite's fake DNS zone rather than a route that does not exist.

chrisholloway5 committed Sep 9, 2026

Linux: an Installing on Linux page from the packages to a delivered message, the relocation runbook as a page, the Installation paths diagnostic in the Monitoring table, the domain routes on the REST page, and the platform notes the Settings and Capabilities pages needed

chrisholloway5 committed Sep 9, 2026

The wiki rewritten in depth: 141 diagrams drawn from the code, every reference page made exhaustive, and twenty-one defaults corrected that no page had ever stated The wiki was accurate after this morning's sweep and thin. This is the depth pass the owner asked for: every page read against the code again, every reference page completed, and a diagram wherever a diagram says it better than a paragraph. 141 Mermaid diagrams across 49 pages, each drawn from the handler rather than from memory: the SMTP submission sequence with the checks in the order ProtocolMAIL_ and ProtocolRCPT_ actually run them, the IMAP session state machine from the per-command authentication guards, the DMARC evaluation, the delivery pipeline and its retry arithmetic, the ACME renewal state machine, the spam decision from connection to delivery, the schema chain, the component and threading models of the whole server, the CI workflows and what each one gates, the release draft-sign-publish flow, and a map of the journeys through the wiki itself on the landing page. The reference pages are now exhaustive rather than representative: every route with its method, authentication, request and response shape and its error codes; every [Settings] key with its default, its effect and whether it needs a restart; every port with the key that opens it; every rule criterion and action; every Sieve extension the server advertises; every metric the listener exposes. Twenty-one facts were wrong or absent, and each is corrected against the code rather than adjusted. The ones that will save somebody an afternoon: IMAP SASL PLAIN and SCRAM are not advertised on a default install, which looks exactly like a client bug; SMTP AUTH PLAIN is off by default too; DMARC checking is on while SPF and DKIM as scored tests are off, and the DMARC test evaluates both itself regardless; the seeded DNSBL and SURBL servers are inactive; a new mailbox contains INBOX and nothing else, which is the real cause of the classic missing Sent folder; MTA-STS hosting and autoconfiguration default on while both web-service ports default to 0, so the shipped default is features on with nothing listening; and TLS-RPT and DMARC report sending are inert until their From address is set, with each completed day discarded unsent. Eleven screenshots are named as wanted, with what each should show. The existing images are from a 6.2.10-era build and the pages say so where it matters.

chrisholloway5 committed Sep 8, 2026

Every page read against the tree on 8 September 2026: the release and schema stamps (6.2.27, schema 6031, 2,124 tests), the routes, keys and pages that were missing, the listener paragraphs that were false, and the unreleased work labelled as such An audit of all 51 pages against master produced about 360 findings on 43 of them, applied here. The largest: the APIs reference lacked 47 routes and described the listeners as single-threaded HTTP/1.0 (they run on the Boost.Asio HTTP/1.1 server); the settings reference lacked the fourteen Update* keys and IMAPCompressionEnabled and counted 195 keys instead of 236; every "current release" stamp said 6.2.24; Changes Since 6.2.10 ended three releases and one schema step early; Architecture said the optional listeners were deliberately not Boost.Asio and built their own SSL contexts (neither is true); the upgrading pages still warned of a silent-upgrade hang fixed in 6.2.23; the Control Panel pages knew nothing of the seventeen languages, the Updates card or the stalled-mail page; and two pages did not render (a header inside a code block, CR and TAB bytes in file names). Anything in the tree but not in v6.2.27 - the live update, the self-service portal and /api/v1/me, the HttpServer listeners, IMAP COMPRESS=DEFLATE, the seventeen-language Control Panel, the Control Deck views - is documented and marked "in the tree after 6.2.27, not yet released". The Control Panel screenshots are still from a 6.2.10 build and the pages now say so.

chrisholloway5 committed Sep 8, 2026

The hMailServer 6.2.24 wiki: the corrected manual, the runbooks, and the references generated from the code

chrisholloway5 committed Sep 4, 2026