Stalwart
@thomas/stalwartv2026.11.19.1
01README
Non-destructive administration of a Stalwart mail server (0.16 and v1) over its JMAP-over-HTTP management API, authenticated with a scoped admin API key. Reads domains, accounts, aliases, groups, DMARC/TLS reports, the outbound queue and server health. Creates or updates accounts and aliases, groups, mailing lists and roles (idempotent); changes server settings; installs and reloads certificates; reloads config; and deactivates or reactivates domains and accounts. No hard deletes: the reversible set-state methods are the only way to disable anything. Secrets (account passwords, certificate keys) are sent once and never read back.
02Behaviors
@thomas/stalwartv2026.11.19.1stalwart.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| apiUrl | string | Stalwart base URL, e.g. https://mail.example.com (no trailing /jmap). |
| apiKey | string | Scoped admin API key, sent as a Bearer token. Supply via vault: |
| accountId? | string | JMAP management accountId. Omit to resolve the session's primary account. |
| httpTimeoutMs? | coerce.number | Per-request timeout (ms) for JMAP and REST calls, covering the whole response |
fn domain_list()
List mail domains (factory: one `domain` per domain). Read-only.
fn account_list()
List accounts — individuals and groups (factory: one `account` each).
fn alias_list(account?: string)
List alias addresses (factory: one `alias` per alias), optionally
| Argument | Type | Description |
|---|---|---|
| account? | string | Filter to one account's aliases (local part or full address) |
fn role_list()
List roles and the permissions they grant (factory: one `role` each).
fn group_list()
List group accounts (factory: one `group` each). Read-only. Note:
fn mailing_list_list()
List mailing lists and their recipients (factory: one `mailing-list`
fn queue_list()
List queued outbound messages (factory: one `queue-item` each).
fn report_query(kind?: enum)
List received DMARC/TLS aggregate reports (factory: one `report` each).
| Argument | Type | Description |
|---|---|---|
| kind? | enum | Which received aggregate reports to list |
fn role_ensure(preset?: enum, name?: string)
Create or converge a role (idempotent by name). Pass a `preset`
| Argument | Type | Description |
|---|---|---|
| preset? | enum | Use a built-in curated permission set (supplies name + permissions) |
| name? | string | Role name/description. Required unless `preset` is given (overrides |
fn role_assign(account: string, role: string)
Assign one role to an account (idempotent). `role` is `admin`,
| Argument | Type | Description |
|---|---|---|
| account | string | Target account: full address, or a local part that only one account has |
| role | string | The one role to assign: `admin`, `user`, or a custom role's |
fn account_ensure(email: string, description?: string, role?: string, password?: string)
Create or converge an individual mailbox (idempotent by address).
| Argument | Type | Description |
|---|---|---|
| string | Full primary address, e.g. alice@example.com | |
| description? | string | Display name / description |
| role? | string | Role: admin | user | a custom role name (default `user` on create) |
| password? | string | Initial password, set only when the account is created (hashed by |
fn mailing_list_ensure(address: string, description?: string)
Create or converge a mailing list (idempotent by address). Resolves the
| Argument | Type | Description |
|---|---|---|
| address | string | Full list address, e.g. team@example.com |
| description? | string |
fn group_ensure(address: string, description?: string)
Create or converge a group account (idempotent by address). Membership
| Argument | Type | Description |
|---|---|---|
| address | string | Full group address, e.g. staff@example.com |
| description? | string |
fn domain_set_state(domain: string)
Enable or disable a domain (reversible, via `enable`, or `isEnabled`
| Argument | Type | Description |
|---|---|---|
| domain | string | Domain name, e.g. example.com |
fn account_set_state(account: string)
Disable or re-enable an account without deleting it. Disable replaces
| Argument | Type | Description |
|---|---|---|
| account | string | Account: full address, or a local part that only one account has |
fn account_set_password(account: string, password: string)
Set an individual account's login password, replacing any it had.
| Argument | Type | Description |
|---|---|---|
| account | string | Account: full address, or a local part that only one account has |
| password | string | New password (hashed by Stalwart; never read back). Pass a vault reference. |
fn settings_get(kind: enum)
Read a server settings singleton (http, system, spam-classifier, …).
| Argument | Type | Description |
|---|---|---|
| kind | enum | Which settings singleton to read |
fn settings_set(kind: enum, webPushKey?: string, reload?: boolean)
Set the top-level fields in `patch` on a settings singleton
| Argument | Type | Description |
|---|---|---|
| kind | enum | Which settings singleton to update |
| webPushKey? | string | jmap only: the Web Push key, stored as a Text secret. Pass it as a |
| reload? | boolean | Run a settings reload afterwards, even when nothing changed, so the |
fn reload()
Reload server settings (applies registry changes without a restart).
fn update_apps()
Download the web applications (the admin and account UI) again,
fn certificate_install(certificate: string, privateKey: string, certificateId?: string, reload?: boolean)
Install a TLS certificate (PEM cert + key) and reload certificates.
| Argument | Type | Description |
|---|---|---|
| certificate | string | PEM certificate (full chain) |
| privateKey | string | PEM private key — sent once, never read back |
| certificateId? | string | Update a specific certificate id; otherwise update the sole existing |
| reload? | boolean | Run reload-certificates after install so the new cert is served |
fn reload_certificates()
Reload TLS certificates from the store (no restart).
fn health_status()
Server health: edition and permissions (GET /api/account) plus every
fn session_dump()
Fetch the JMAP session resource (/.well-known/jmap) and record the
fn jmap_probe(type: string, limit?: coerce.number)
Discovery probe: run `<type>/query` then `<type>/get` for one type and
| Argument | Type | Description |
|---|---|---|
| type | string | JMAP object type to probe, e.g. Principal, x:Domain, x:SpamClassifier |
| limit? | coerce.number | Max ids to query (kept small — this is a discovery probe) |
Resources
domain(infinite)— A mail domain record
account(infinite)— An account / individual principal (emails[] = primary + aliases)
alias(infinite)— An alias address — a view over a principal's emails[]
group(infinite)— A group principal (membership is tracked on member accounts)
mailing-list(infinite)— A mailing-list principal and its members
report(infinite)— A DMARC/TLS aggregate report (read-only)
queue-item(infinite)— An outbound mail-queue entry (read-only)
health(infinite)— Server health: edition, permissions and Prometheus metrics
certificate(infinite)— A TLS certificate install result (key never echoed)
role(infinite)— A role and the permissions it grants
settings(infinite)— A server settings singleton (http, system, …)
state-result(infinite)— Result of a reversible deactivate/reactivate or a reload
probe(infinite)— Discovery probe: the wire shape of one JMAP object type
session(infinite)— The JMAP session resource: advertised capabilities + accounts
03Previous Versions
2026.11.16.1MIT
Modified 1 behaviors
2026.10.29.2MIT
2026.10.29.1MIT(was none)
2026.10.11.1
Added 1 behaviors
2026.06.24.1
04Stats
A
100 / 100
Downloads
41
Archive size
50.9 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Docs keep secrets in a vault1/1earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License2/2earned
- Verified public repository2/2earned
05Platforms
06Labels