The REST API is the alternative to COM for automating hMailServer, and the only administration interface that works from a machine that is not running Windows. This guide covers how to turn the listener on, the three credentials it takes and the roles that narrow them, how one-time codes behave since 6.3.4, the OpenAPI document the server emits, and a set of curl examples that use only routes the project's own documents name. The one thing to know first: the listener is off as shipped (RestApiPort=0), and since 6.3.4 RestApiPort is a setting stored in the database. Editing the [Settings] section of hMailServer.ini does not turn the API on once the server has stored the key.

Turning the listener on

Four settings shape the listener.

Since 6.3.4 the database is the settings store (schema 6042) and the [Settings] section of hMailServer.ini is its copy. A key the server has never stored is taken in from the file at the next start, so on a fresh installation an edit made before the first start still works; once the key is stored, the database's value is the one used. Settings: what is not stock, when a save takes effect covers the store itself, why an edited line is put back (HM5804) and [SettingsOverride]. Where the stored value is changed depends on the platform.

sudo hmailserver --set-setting RestApiPort=8443
sudo systemctl restart hmailserver

--set-setting checks what it is given: a port must be a number from 0 to 65535 and RestApiBindAddress an IP address or localhost.

On Linux this matters most, because there the REST API is the administration interface. The packaged /etc/hmailserver/hMailServer.ini ships RestApiPort=0 and RestApiBindAddress=127.0.0.1 under [Settings], so the first start stores both, and changing those lines afterwards turns nothing on. The one part of the file that still decides a stored key is a [SettingsOverride] section, applied over the store at every start and reported as HM5807 each time; the wiki gives it as the route where neither the Control Panel nor COM is available.

The new value waits for a reinitialise. Since 6.3.4 most settings apply when they are saved, but RestApiPort, RestApiBindAddress, RestApiCertificateFile and RestApiPrivateKeyFile are among the 28 keys marked reinitialize, because the listener binds and its TLS context is built when the servers start. They take effect at Apply now in the Control Panel (Windows) or the Control Deck, at Application.Reinitialize over COM (Windows), at POST /api/v1/server/reinitialize, or at a restart of the service.

The listener can refuse to start, and each refusal is written once to the application log.

The Listening on line is the only proof that the listener is up. The loopback exemption is a string comparison against 127.0.0.1, localhost and ::1; 127.0.0.2 and ::ffff:127.0.0.1 do not qualify. The TLS configuration is the one the mail protocols use (cipher list, protocol switches, TlsKeyExchangeGroups), with a TLS 1.2 minimum applied on top, so opening an older protocol for a mail client does not open it for the management API.

The three credentials

The two Basic forms are told apart before either password is tried: any user name but administrator is treated as a mailbox address and goes down the path an IMAP logon takes, with the same lockout and auto-ban. An account is never tested against the administrator password.

API keys are the credential for scripts. A key is read-only unless it is made with "scope":"full", expires after 90 days unless the request names an expires (there is no "never expires"), and may be narrowed to named domains and to a source address, range or CIDR. Only the SHA-256 of a key is stored, in hMailServerApiKeys.ini beside hMailServer.ini, and that file is read again at every authentication attempt, so removing a key's section revokes it on the next request.

# Administrator password only: a key can never make or revoke keys
curl -u Administrator:your-admin-password \
     -H "Content-Type: application/json" \
     -d '{"label":"backup monitor","scope":"readonly","expires":"2027-01-01 00:00:00"}' \
     http://127.0.0.1:8443/api/v1/apikeys

{"id":"3f9a1c4b5d6e7f80","label":"backup monitor","scope":"readonly","domains":"",
 "expires":"2027-01-01 00:00:00","allowed_from":"","key":"hmapi_7c1f...c92a"}

key is the clear text. It is returned once and cannot be recovered, so store it then. GET /api/v1/apikeys lists the keys with an expired flag and never a hash; DELETE /api/v1/apikeys/<id> revokes one. The create request takes label (required, at most 64 characters), scope, domains, expires and allowed_from, and since 6.3.4 role and the send API's send_from, send_per_minute and send_per_day.

What no API key reaches. Whatever its scope or role, a key is answered 401 (not 403, so that it learns nothing) on the key store /api/v1/apikeys and on /api/v1/settings/ini, and since 6.3.4 also on /api/v1/audit, /api/v1/alerts, /api/v1/webhooks, the compromised-account review, /api/v1/settings/changed, /api/v1/server/settings/pending, an account's export, the address erasure and the second factor's enrolment. In the other direction, since 6.3.4 a key is the only credential POST /api/v1/send takes (a key naming a sender) and the only one /scim/v2 takes (a key whose role holds provision).

Roles, since 6.3.4

A role is a named set of permissions, and an assignment gives an account a role in named domains (schema 6047). Nothing changes on upgrade: an account with no assignment holds what its admin level has always given it, and a key without a role is what it always was: Scope=full is serveradmin and Scope=readonly is auditor. A key is given a role with role on POST /api/v1/apikeys; an account is given one at /api/v1/role-assignments by a credential holding manage_roles.

What a refusal says. A route a role may not call answers 403 naming the role and the permission, for example the role 'helpdesk' does not hold the permission 'manage_settings'. An address in a domain the role does not reach answers the role 'helpdesk' does not reach that domain whether or not the account exists. A request authenticated with an app password never carries the account's role.

Administrator roles end to end has the built-in roles and their permissions, giving a role on each surface, custom roles, and the two stores, /api/v1/apikeys and /api/v1/settings/ini, that answer to the administrator password alone, not even to an account holding serveradmin.

One-time codes

When a second factor is enrolled on the administrator credential, the code travels in an extra header:

curl -u Administrator:your-admin-password \
     -H "X-hMailServer-OTP: 123456" \
     http://127.0.0.1:8443/api/v1/status

Without it the answer is the one 401 on this listener that says what is missing:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="hMailServer"
X-hMailServer-OTP: required
Cache-Control: no-store

{"error":"authentication failed","second_factor":"required"}

A missing code is not counted towards the auto-ban; a wrong code is.

Since 6.3.4 a one-time code is taken once, over COM and over REST, for the administrator and for an account alike. A code the server has accepted is refused if it comes again. The consequence for automation is direct: a script that sent the administrator's password and a code with every request now has only its first request in each half minute accepted. The others are refused with 401 and are not counted as wrong codes, so such a script does not lock the administrator out. The changelog names the two remedies: sign in once with POST /api/v1/session and use the hmailsession cookie from there, or use an API key.

# Sign in once; the password and the code travel on this request alone
curl -c cookies.txt -u Administrator:your-admin-password \
     -H "X-hMailServer-OTP: 123456" \
     -X POST http://127.0.0.1:8443/api/v1/session

# Reads carry the cookie
curl -b cookies.txt http://127.0.0.1:8443/api/v1/status

# Anything that changes something also carries the CSRF header
curl -b cookies.txt -X POST -H "X-Requested-With: hMailServer" \
     http://127.0.0.1:8443/api/v1/queue/81234/retry

# Sign out
curl -b cookies.txt -X DELETE -H "X-Requested-With: hMailServer" \
     http://127.0.0.1:8443/api/v1/session

The session rules are enforced by the server: 30 minutes idle and 12 hours from sign-in until a session policy sets others (since 6.3.4, session_idle_seconds and session_lifetime_seconds), at most 1000 sessions, and every session dropped when the listener stops. A cookie-authenticated request that is not GET or HEAD without X-Requested-With: hMailServer is refused with 403. Somebody who is asked for a code twice within half a minute, to sign in to the Control Deck and then to register a passkey for example, waits for the authenticator's next code.

Two further changes in 6.3.4 belong here. A wrong code is counted against a budget of five in fifteen minutes, after which no code is taken for fifteen minutes; on the administrator's Basic sign-in the answer is then 429 with code second_factor_locked and Retry-After. And for an account, one of its one-time recovery codes, in X-hMailServer-Recovery-Code, is taken wherever the authenticator's code is asked for.

The administrator signs in at POST /api/v1/session with HTTP Basic, and with the code in X-hMailServer-OTP when a second factor is enrolled: AccountRecovery.md names the header for this route, the 6.3.4 changelog gives the session as the remedy above, and the Control Deck signs in that way. The wiki's credentials table, which lists /api/v1/session among the routes the administrator password does not reach, is out of date on this.

How a request is judged

The server tries Bearer, then Basic, then the session cookie. It then applies the CSRF check for cookie-authenticated writes (and, since 6.3.7, refuses any state-changing request that carries a credential when the browser reports it as cross-site, by Sec-Fetch-Site or an Origin that is not this server's) and the rate budget of 200 requests in a fixed 10-second window per credential, turns the method and path into a route kind, and decides on that kind in one place before any handler runs.

• Read-only is decided by route kind, not by HTTP method. A read-only key on a mutating route is answered 403 with this api key is read-only.
• A key with a domain list is refused server-wide resources outright: the queue, the quarantine, IP ranges, certificates, rules, logs, the backup and the settings among them. On a route that names a domain or an address outside its list the answer is 403 with this api key is not permitted for that domain.
• Routing is exact. Method and path must match after the query string is removed, a trailing slash is a different path, and an id in a queue, quarantine, IP-range, archive or /api/v1/me/... path must be 1 to 18 decimal digits and greater than zero, or the answer is 404.

The OpenAPI document

GET /api/v1/openapi.json answers the API's description to the administrator password or to any key, a read-only one included. The wiki's advice is that this document is the count to trust: in 6.3.4 it names 441 paths and 621 path-and-method operations, 413 and 585 of them under /api/, against 146 and 219 in 6.3.3. The rest are /scim/v2, the sign-in, reset and reading pages, the list manager's pages and the static catalogues and scripts.

The Control Deck draws its settings groups from this document, and since 6.3.4 the document gives the ini-backed rows of the settings groups an x-applies mark saying when a save takes effect. The APIs Reference describes it as a static OpenAPI 3.0.3 document and records where its text is not accurate:

• the summary of /api/v1/status mentions uptime, and the handler returns no uptime field;
• the text for /api/v1/settings/ini still describes the file as the store, where since 6.3.4 the value goes to the database first.

Settings saved and not yet running

Since 6.3.4 a key marked reinitialize or restart whose stored value is not the value the server is running on is pending. The list is recomputed at every request.

All but the last answer to the administrator password alone. A DELETE is now the only way to return a stored key to its default, because deleting a line from the file no longer does. A reinitialise restarts the REST listener with the other services, so it ends a Control Deck session; poll /api/v1/status until it answers again.

Worked examples

These use the loopback, plain-HTTP shape that RestApiPort=8443 and RestApiBindAddress=127.0.0.1 give; put the port that was stored in place of 8443. With a certificate configured, change http:// to https://. They present the administrator password on every request, which works while no second factor is enrolled; with one enrolled, use the session above or an API key.

# Status: state is 0 Unknown, 1 Stopped, 2 Starting, 3 Running, 4 Stopping
curl -u Administrator:pw http://127.0.0.1:8443/api/v1/status

# Domains and accounts
curl -u Administrator:pw http://127.0.0.1:8443/api/v1/domains
curl -u Administrator:pw http://127.0.0.1:8443/api/v1/domains/example.com/accounts
curl -u Administrator:pw -H "Content-Type: application/json" \
     -d '{"address":"newuser@example.com","password":"S0me-Long-Passphrase"}' \
     http://127.0.0.1:8443/api/v1/domains/example.com/accounts
curl -u Administrator:pw -X DELETE \
     http://127.0.0.1:8443/api/v1/accounts/newuser@example.com

# The delivery queue
curl -u Administrator:pw http://127.0.0.1:8443/api/v1/queue
curl -u Administrator:pw -X POST http://127.0.0.1:8443/api/v1/queue/81234/retry
curl -u Administrator:pw -X DELETE http://127.0.0.1:8443/api/v1/queue/81234

# Logs and the backup
curl -u Administrator:pw "http://127.0.0.1:8443/api/v1/logs/hmailserver_2026-09-08.log?lines=50"
curl -u Administrator:pw -X POST http://127.0.0.1:8443/api/v1/backup
curl -u Administrator:pw http://127.0.0.1:8443/api/v1/backup

# With a key
curl -H "Authorization: Bearer hmapi_7c1f...c92a" http://127.0.0.1:8443/api/v1/status

# Store another port: it waits for a reinitialise, and the pending list shows both values
curl -u Administrator:pw -X PUT -H "Content-Type: application/json" \
     -d '{"value":"8444"}' http://127.0.0.1:8443/api/v1/settings/ini/RestApiPort
curl -u Administrator:pw http://127.0.0.1:8443/api/v1/server/settings/pending

# Put the running port back; a value put back before anything applied it is no longer pending
curl -u Administrator:pw -X PUT -H "Content-Type: application/json" \
     -d '{"value":"8443"}' http://127.0.0.1:8443/api/v1/settings/ini/RestApiPort

Creating an account answers {"address":"newuser@example.com","created":true}, or 400 for a missing field, 404 {"error":"domain not found"} or 409 {"error":"account already exists"}. In 6.3.4 the create route takes address and password and the other columns of the CSV import as well (first_name, last_name, active, max_size_mb and admin_level), and refuses a field it does not know by name (CommandLine.md). The older statement in the wiki and the APIs Reference, that only address and password are read, no longer holds. For a log, lines defaults to 200 and is capped at 2000.

Limits and status codes

A 401 is deliberately the same for no credential, a wrong password and an unknown, expired or out-of-network key; the application log says which. A request with Transfer-Encoding is answered 411, because the server does not de-chunk. An API response is application/json with Cache-Control: no-store, with exceptions: the static pages and the attachment download serve their own media types, a report asked for with format=csv is text/csv, and every answer under /scim/ is application/scim+json.

Where to read more

• The wiki: The REST API and, for a row per route, APIs Reference section 4.
• The operator documents: Roles.md and SettingsApply.md.
• The public documentation: chapter 24, The REST API, with API keys and the OpenAPI document.
• On this forum: The Control Deck, which is the browser front end for this API; the Linux guide; the 6.3.4 announcement; hmctl and the PowerShell module; the send API and webhooks; and SCIM provisioning and single sign-on.