Written for 6.3.4. hMailServer 6.3.7 (17 October 2026) is a security release that closes gaps in what this guide describes. Over COM an account given serveradmin with a list of domains was the server's administrator, its list aside, and one given domainadmin with a list that left out its own domain administered that domain's ordinary accounts; both are now confined as over REST, so before upgrading give serveradmin with no list to any account that is to administer the whole server over COM, a script's or a Control Panel's account among them. A credential confined to named domains is refused a domain's rename, a domain alias, a custom role's creation, change or deletion, a rule action that reaches the server's own addresses, a route's stored credentials or the event script, a relay host that is not public, and the server-wide metric history, over REST and COM alike; and a role is given or taken away only by a credential that takes in what the account holds now and afterwards, so manage_roles in named domains can no longer take a role from an account whose admin level is the server administrator's. A state-changing REST request that a browser reports as cross-site is refused. In the Control Panel, API & monitoring is Monitoring & alerts and REST API keys is under Sign-in & access; Ctrl+K takes every old title to its page. See the 6.3.7 announcement.
This guide puts administrator roles in one place. Roles are new since 6.3.4 (schema 6047). The one thing to know first: an upgrade changes nobody's authority. The upgrade writes no assignment, and an account with no assignment holds exactly what its admin level has always given it. Nothing narrows until you give somebody a role.
Permissions, roles and assignments
A permission is one thing a credential may do, a role is a named set of permissions, and an assignment gives one account one role in named domains. An account holds at most one role.
Role
For
Reaches when no domain is named
The same as
serveradmin
Everything, including the secrets no other role reads
Every domain
The administrator password, admin level Server, an API key with Scope=full and no role
domainadmin
The accounts, aliases, lists and mailboxes of a domain
The account's own domain
Admin level Domain
helpdesk
Finding an account, resetting its password, unlocking it, and reading where its mail went, and nothing else
The account's own domain
Nothing before 6.3.4
auditor
Reading everything the administration exposes, the audit trail included, and changing nothing
Every domain
An API key with Scope=readonly and no role
The built-in roles cannot be edited or deleted. Their permissions are in the server's code, not the hm_roles table, so a change to the table cannot hand anybody a permission.
The 27 permissions and who holds them
A permission marked server-wide is reached only by a credential with no list of domains. The queue, the quarantine, the archive, the logs and the settings carry every domain's mail, so a role confined to named domains is refused them whatever it holds.
Permission
What it reaches
serveradmin
domainadmin
helpdesk
auditor
administer_server
Everything, secrets such as password hashes and private keys included; COM's "is this the server administrator?"
yes
administer_domain
COM's "is this a domain administrator?"
yes
yes
view_configuration
Status, settings, listeners, certificates, rules, routes, anti-spam lists, the roles and who holds them, alert rules and events, bounce and complaint readings; never a secret
yes
yes
yes
view_accounts
Domains, accounts, aliases, lists, groups (server-wide), fetch accounts
yes
yes
yes
yes
view_mailbox
Another account's folders and messages
yes
yes
yes
view_queue
The delivery queue (server-wide)
yes
yes
view_quarantine
The quarantine (server-wide)
yes
yes
yes
view_archive
The archive (server-wide)
yes
yes
view_logs
The logs (server-wide)
yes
yes
view_message_trace
The message trace; with view_configuration, the reports and a domain's suppression list
yes
yes
yes
yes
view_audit
The audit trail (server-wide)
yes
yes
manage_accounts
Creating, changing and deleting accounts, aliases, lists, groups, fetch accounts and app passwords; a domain's spam traps, DKIM rotation and suppression list; moving a mailbox (needs both domains)
yes
yes
reset_password
POST /api/v1/accounts/{address}/password, Application.ResetPassword
yes
yes
yes
unlock_account
POST /api/v1/accounts/{address}/unlock, Application.UnlockAccount, Account.UnlockMailbox; clearing the logon-failure list (server-wide)
yes
yes
yes
manage_mailbox
Another account's folders, messages and folder rights, a support session, a PST migration job (with manage_accounts)
yes
yes
manage_queue
Retrying or deleting a queued message (server-wide)
yes
manage_quarantine
Releasing or deleting held mail (server-wide)
yes
yes
manage_archive
Holding and releasing archived messages (server-wide)
yes
manage_settings
Every setting, listener, certificate, route, rule and anti-spam list, the alert rules (server-wide); the webmail's branding and file-link policy, a confined credential only its own domains'
yes
manage_domains
Which domains exist (server-wide)
yes
manage_server
Reinitialise, back up, reload scripts, clear caches, install an update, run a pass now (server-wide)
yes
manage_roles
Roles and who holds them (server-wide)
yes
send_through_api
Sending through POST /api/v1/send; only an API key reaches it
yes
provision
SCIM 2.0 at /scim/v2, reads and writes; only an API key reaches it
yes
view_discovery
eDiscovery's cases, searches, holds and exports
yes
yes
manage_discovery
Opening and closing a case, searching, legal holds, exports
yes
manage_inbound_webhooks
Routing an address or a domain to a URL, as much as reading every message the route takes
yes
Four rules sit beside the table:
The auditor reads mail. It holds view_mailbox; the help desk does not.
The reports need two permissions. GET /api/v1/reports needs view_configuration and view_message_trace, because it says who mails whom. domainadmin and auditor read them; helpdesk is refused, and the Deck leaves the Reports view out for any role without both.
The trace follows the role's reach. A confined help desk traces one whole address in a domain it reaches and sees only events naming that address exactly:
[email protected] does not also show
[email protected].
Clearing the logon-failure list is server-wide. hm_logon_failures records only the address a failure came from, with no account or domain, so a confined help desk is refused POST /api/v1/settings/logon-failures/clear, and Settings.ClearLogonFailureList answers the server administrator alone. The help desk unlocks one account with POST /api/v1/accounts/{address}/unlock instead; a password reset clears the lockout too. A ban already placed is an IP range under /api/v1/ipranges, which needs manage_settings.
What only serveradmin has
Reading a secret. No view_ permission covers a password hash or a private key: an auditor that could read one would be an offline attack away from being every role.
Handing out authority. No custom role may hold administer_server, administer_domain or manage_roles, and a credential may never give a role holding a permission, or reaching a domain, that it does not hold itself.
Taking over a wider account. A credential may not reset the password of, or change, an account whose whole authority it does not take in. A help desk is refused a domain administrator's or an auditor's password, even in its own domain, because otherwise it could sign in as them; a domain administrator is refused an auditor's. Where the server administrator's own mailbox is in a domain somebody else administers, that domain's administrator is refused all of these on it, over REST and COM. Over COM this is asked where the write is made, not where the object was reached: Account.Save, Account.Delete, Account.MoveTo, Application.ResetPassword, the app passwords and every write to what is in an account (FetchAccount.Save, Rule.Save, IMAPFolder.Save, Message.Save and the rest) ask that the credential reach the account and take in its authority. An event script's objects carry no credential and are left as they were. Roles.md lists every route and COM member that asks this.
Which domains a role reaches
Credential
No domains named
*
A list
An assignment of serveradmin or auditor
Every domain
Every domain
Only those
An assignment of any other role, custom ones included
The account's own domain
Every domain
Only those
An API key's Domains= line, whatever its role
Every domain
Matches no domain
Only those
A custom role holding a server-wide permission needs * before an account can use it at all. The listings answer every_domain over REST, and a fourth field over COM. A credential confined to named domains sees only the assignments of accounts in those domains.
Giving a role, surface by surface
Control Panel (Windows only): Accounts & domains → Administrator roles lists the roles and who holds them. Type an address, choose a role, optionally name the domains, and press Give the role; select a row and press Take the role away. It applies at once.
Control Deck (Windows and Linux): the Roles view does the same.
REST: giving or taking away a role needs manage_roles, which only serveradmin holds and which is server-wide: the administrator password, or a serveradmin credential reaching every domain.
PUT /api/v1/role-assignments/
[email protected] {"role":"helpdesk","domains":"example.test,example.org"}
DELETE /api/v1/role-assignments/
[email protected]
GET /api/v1/role-assignments
GET /api/v1/roles
COM (Windows only): an empty role name takes the role away, and Account.RoleName, RoleDomains and RolePermissions read it back:
$app = New-Object -ComObject 'hMailServer.Application'
$account = $app.Authenticate('Administrator', 'your-admin-password')
if (-not $account) { throw 'Authentication failed.' }
$app.AssignRole('
[email protected]', 'helpdesk', 'example.test')
$helen = $app.Domains.ItemByName('example.test').Accounts.ItemByAddress('
[email protected]')
$helen.RoleName; $helen.RoleDomains; $helen.RolePermissions
With a second factor on the administrator, Authenticate refuses and the script uses AuthenticateWithCode. Application.CurrentRole and CurrentPermissions say what a session holds.
An API key: POST /api/v1/apikeys with "role":"helpdesk" writes a Role= line to hMailServerApiKeys.ini. The key store answers to the administrator password alone. The Deck's API keys view, signed in with that password, also makes a key with a role and its domains, showing the token once.
curl -u Administrator:your-admin-password \
-H "Content-Type: application/json" \
-d '{"label":"help desk tool","role":"helpdesk","domains":"example.test"}' \
https://<host>:8045/api/v1/apikeys
Use the address and port your listener answers on; bound to loopback with no certificate, it is http://127.0.0.1:8045 (https:// once a certificate, or an ACME one, is in place). A key's role decides what it reaches. The Control Panel's REST API keys page, as its reference describes it, names no role; give a key its role over REST or in the Deck. No API key signs in to the Deck.
Custom roles are made over REST from a name, a description and a comma-separated permission list; both editors list them and give them out. A role that releases held mail holds server-wide permissions, so it is given with * and reaches every domain's held mail:
POST /api/v1/roles {"name":"quarantine-desk","description":"releases held mail","permissions":"view_quarantine,manage_quarantine"}
PUT /api/v1/role-assignments/
[email protected] {"role":"quarantine-desk","domains":"*"}
A permission the server does not know is dropped, not refused, so a custom role ends with less authority than it asked for, never more. A custom role somebody holds cannot be deleted: DELETE /api/v1/roles/{name} answers 409 saying how many accounts hold it, and the Deck's Delete shows that sentence. Give each holder another role or take this one away first; assignments are never removed for you, because an account with none falls back to its admin level. A built-in role answers 400, and COM cannot delete a role. An assignment decides even when its role holds nothing: holders of a custom role whose permissions name nothing this version knows are ordinary accounts, not their admin level.
Where each role works
Role
Control Deck
REST API
Control Panel (COM)
serveradmin
Every view
Every route
Every page
domainadmin
Dashboard, DANE / TLSA, domains, fetch accounts, lists, roles and reports for its domains
Its domains' accounts, aliases, lists and mailboxes, the status, who holds a role there
Domains and Administrator roles
helpdesk
Domains, fetch accounts and lists, with Reset password and Unlock on every account
The reset, the unlock, the account listings, the trace of an address in its domains
Welcome and About only; Application.ResetPassword, UnlockAccount and GlobalObjects.MessageTrace answer a script
auditor
Every view that reads, the audit trail and reports included
Every read, the audit trail and alerts included; every write refused
Welcome, About and Administrator roles
The help desk and the auditor work in the Deck. COM's settings objects answer only the server administrator, so an auditor reads the configuration through the Deck or REST. A domain administrator is not shown the settings, rules, routes, remote domains, certificates, ports, IP ranges, groups, backup, server messages, queue, logs or audit trail, which are server-wide. The quarantine is server-wide as well, so a domain administrator confined to its domain is refused it.
Hiding a page is a courtesy, not the boundary. The server refuses the request whatever a page draws, and a Control Panel connected to a server that predates roles shows every page.
A role holder signs in with its own address and password, and its second factor where it has one. An app password never carries the role: over REST it is an ordinary account's request, and COM's Application.Authenticate and AuthenticateWithCode treat it as a wrong password. A support session into a mailbox does not carry the person's role either. A role holder's own mail and settings under /api/v1/me stay its own.
Setting up a help desk
Turn the REST listener on if it is off. It needs RestApiPort set, RestApiBindAddress set to an address staff can reach (the default, 127.0.0.1, serves this machine alone), a certificate unless it is bound to loopback, and a name staff can reach. On Windows set them on the Control Panel's API & monitoring page (Monitoring & alerts since 6.3.7) and press Apply now, since they wait for a reinitialise. On Linux run sudo hmailserver --set-setting RestApiPort=8045 and the same for RestApiBindAddress and, for any address but loopback, RestApiCertificateFile and RestApiPrivateKeyFile (or let an ACME certificate stand in), then sudo systemctl restart hmailserver. The Control Deck topic has the details.
Give each person a mailbox of their own; the role goes to that account.
Decide the domains. With none named, helpdesk reaches only the account's own domain; name several, comma separated, for a desk serving more.
Give the role on any surface above and check it with GET /api/v1/role-assignments or the Roles view.
The person signs in to the Deck at https://<host>:8045/ as themselves, then uses Reset password or Unlock on an account.
Tell them the limits: no mail reading, no reports, no domain administrator's or auditor's password, no removing a ban, and, when confined, no clearing of the logon-failure list.
Each change the help desk makes is on the audit trail as its own, over COM and REST, with actor type account and a detail ending [role: helpdesk].
What a refusal says
A permission the role lacks: 403 naming both, for example the role 'helpdesk' does not hold the permission 'manage_settings'.
A domain it does not reach: the role 'helpdesk' does not reach that domain, whether or not the account exists, so nobody can list another domain's mailboxes one request at a time. Over COM, Application.ResetPassword and UnlockAccount answer No such account. for both.
An account wider than the credential: that account holds authority this credential does not.
Over COM, since 6.3.4 a refusal carries the server's sentence rather than a bare Exception from HRESULT: 0x800403E9.
An API key on the key store, the [Settings] routes, the audit trail or the alerts: 401 with {"error":"authentication failed"}, the same as "not a key".
The two stores only the administrator password opens
The key store (/api/v1/apikeys) and the [Settings] section of hMailServer.ini (/api/v1/settings/ini) answer to the administrator password and nothing else: not an account holding serveradmin, not a key of any role or scope. A key that could mint keys could issue itself an unrestricted replacement, and the file holds the server's secrets. An account is refused 403 with the reason, a key 401.
The audit trail (/api/v1/audit) and the alerts (/api/v1/alerts/...) are refused to every API key with the same 401, so a stolen key cannot read what it did or silence the alerting. An account whose role reaches every domain reaches them through view_audit, view_configuration, manage_settings or manage_server; a confined role is refused them.
Upgrades, the audit trail and backups
The upgrade. Schema step 6047 adds hm_roles, seeded with the four built-in rows, and hm_roleassignments, and writes no assignment. Roles are data, not settings: nothing goes into hm_settings or hMailServer.ini.
The audit trail. Every role created, changed or deleted, and every role given or taken away, is a row naming the credential that did it; an assignment's row reads like role: helpdesk -> auditor; domains: the account's own domain -> every domain. The actor type follows the role: the administrator password and holders of serveradmin or domainadmin are administrator, every other account is account.
Backup and restore. An account's assignment travels with it, by role name, and the custom roles travel whenever the domains or the settings do, restored first. A role the restoring server already has is kept as it is, with any difference named in the backup log. The admin level waits until the assignment is written, so a restore that stops part-way leaves no account wider than its role. An assignment naming a role neither side has is dropped, the level stays withheld, and HM6129 names the account. No archive carries the API key store.
What it does not do
No mapping from an identity provider. There is no claims mapping; an identity provider saying somebody is an administrator is not obeyed. The server's roles and oidc_administrators or saml_administrators decide.
No role on an app password or a support session.
No Control Panel or COM on Linux: roles are given there in the Deck and over REST.
Where to read more
Roles.md, the authority on all of this.
Sign-in and Identity §7, The Control Deck, The REST API §2 and The COM API and Scripting §23.2.
AlertsAndAuditTrail.md, Backup.md and Reports.md.
On this forum: The Control Deck: browser administration at /, The REST API: turning it on, credentials and roles, The COM API on Windows, Hardening a public mail server, Alerts and the audit trail and IP ranges, auto-ban and lockout.
