Skip to main content

Stalwart

@thomas/stalwartv2026.11.19.1· MIT· 2d agoBEHAVIORS
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.

02Behaviors1
@thomas/stalwartv2026.11.19.1stalwart.ts

Global Arguments

ArgumentTypeDescription
apiUrlstringStalwart base URL, e.g. https://mail.example.com (no trailing /jmap).
apiKeystringScoped admin API key, sent as a Bearer token. Supply via vault:
accountId?stringJMAP management accountId. Omit to resolve the session's primary account.
httpTimeoutMs?coerce.numberPer-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
ArgumentTypeDescription
account?stringFilter 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).
ArgumentTypeDescription
kind?enumWhich received aggregate reports to list
fn role_ensure(preset?: enum, name?: string)
Create or converge a role (idempotent by name). Pass a `preset`
ArgumentTypeDescription
preset?enumUse a built-in curated permission set (supplies name + permissions)
name?stringRole 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`,
ArgumentTypeDescription
accountstringTarget account: full address, or a local part that only one account has
rolestringThe 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).
ArgumentTypeDescription
emailstringFull primary address, e.g. alice@example.com
description?stringDisplay name / description
role?stringRole: admin | user | a custom role name (default `user` on create)
password?stringInitial 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
ArgumentTypeDescription
addressstringFull 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
ArgumentTypeDescription
addressstringFull 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`
ArgumentTypeDescription
domainstringDomain name, e.g. example.com
fn account_set_state(account: string)
Disable or re-enable an account without deleting it. Disable replaces
ArgumentTypeDescription
accountstringAccount: 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.
ArgumentTypeDescription
accountstringAccount: full address, or a local part that only one account has
passwordstringNew 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, …).
ArgumentTypeDescription
kindenumWhich settings singleton to read
fn settings_set(kind: enum, webPushKey?: string, reload?: boolean)
Set the top-level fields in `patch` on a settings singleton
ArgumentTypeDescription
kindenumWhich settings singleton to update
webPushKey?stringjmap only: the Web Push key, stored as a Text secret. Pass it as a
reload?booleanRun 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.
ArgumentTypeDescription
certificatestringPEM certificate (full chain)
privateKeystringPEM private key — sent once, never read back
certificateId?stringUpdate a specific certificate id; otherwise update the sole existing
reload?booleanRun 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
ArgumentTypeDescription
typestringJMAP object type to probe, e.g. Principal, x:Domain, x:SpamClassifier
limit?coerce.numberMax 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 Versions5
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