The REST API

The REST API

This page began as a chapter of the 6.2.10 manual and has been corrected for 6.2.24. The Control Panel's pages are grouped differently now, so the paths below use today's groups; the TLS ports 465, 993 and 995 exist only after you create them on the TCP/IP ports page (a fresh install seeds 25, 587, 110 and 143); and everything added since 6.2.10 is in Changes Since 6.2.10. Where a value here disagrees with the Settings Reference, which is generated from the code, the reference is right.

A modern alternative to COM for automation, and the only option from a non-Windows machine.

RestApiPort=8443
RestApiBindAddress=127.0.0.1

Authentication is one of: HTTP Basic with the administrator password (Administrator:<password>; when a second factor is enrolled on that credential the request also carries X-hMailServer-OTP: <code>), or a Bearer API key (Authorization: Bearer hmapi_..., created on the REST API keys page or with POST /api/v1/apikeys; read-only by default, expiring, optionally limited to named domains and source addresses — the preferred credential for scripts). In the tree after 6.2.27, not yet in a published release: an account's own address and password reach the self-service routes under /api/v1/me and the /portal page, and nothing else. The full route table, the key store and the credential rules are in APIs Reference.

TLS is required unless bound to 127.0.0.1, localhost or ::1 — the listener refuses to start otherwise ("TLS certificate is required unless bound to 127.0.0.1 or ::1. Set RestApiCertificateFile and RestApiPrivateKeyFile."). With no certificate configured it uses the ACME certificate when one exists.

Method	Endpoint	Does
GET	/api/v1/status	Server status and session counts
GET	/api/v1/domains	List domains
GET / POST	/api/v1/domains/<name>/accounts	List / create accounts
DELETE	/api/v1/accounts/<address>	Delete an account
GET	/api/v1/domains/<name>/aliases	List a domain's aliases
GET / POST	/api/v1/domains/<name>/lists	List / create distribution lists
DELETE	/api/v1/lists/<address>	Delete a distribution list
GET	/api/v1/domains/<name>/dkim	A domain's DKIM signing configuration
GET	/api/v1/queue	The delivery queue
POST	/api/v1/queue/<id>/retry	Retry a queued message
DELETE	/api/v1/queue/<id>	Delete a queued message
GET	/api/v1/quarantine	Quarantined messages
POST	/api/v1/quarantine/<id>/release	Release one to its recipients
DELETE	/api/v1/quarantine/<id>	Delete one
GET	/api/v1/archive?...	Search the archive index; /archive/<id> one entry; POST/DELETE /archive/<id>/hold legal hold
GET / POST	/api/v1/ipranges	List / create IP ranges; DELETE /api/v1/ipranges/<id>
GET	/api/v1/certificates	The SSL certificates (never a key password)
GET	/api/v1/rules	The global rules
GET	/api/v1/logs, /api/v1/logs/<name>?lines=N	Log files and a log's tail
GET / POST	/api/v1/backup	Backup status / start a backup
GET	/api/v1/settings	A read-only snapshot of server-wide settings
GET	/api/v1/tlsa	Publish-ready DANE TLSA records
GET	/api/v1/srv	Publish-ready client-discovery SRV records
GET	`/api/v1/metrics/history?metric=&range=24h	7d
GET / POST / DELETE	/api/v1/apikeys[/<id>]	Manage API keys (administrator password only)
GET	/api/v1/openapi.json	The OpenAPI description

In the tree after 6.2.27, not yet in a published release: GET /api/v1/update and POST /api/v1/update/check|download|install (the live update), GET /portal (the self-service sign-in page) and the account's own routes under /api/v1/me (state, password, automatic reply, quarantine, folders, messages, search, send, drafts, attachments, settings, Sieve filters) with POST/DELETE /api/v1/session for browser sessions. Every route, its credential rules and its JSON shape are in APIs Reference section 4.

# plain HTTP: the listener is bound to loopback and no certificate is configured
curl -u Administrator:your-admin-password http://127.0.0.1:8443/api/v1/status
# with RestApiCertificateFile/RestApiPrivateKeyFile (or an ACME certificate) set, use https://

---