Stalwart

https://stalw.art/docs/
Admin
Stalwart is an open-source, Rust-built mail and collaboration server supporting various protocols...
Tokens:819,764
Snippets:7,680
Trust Score:9.4
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Set up MinIO for store tests

Source: https://stalw.art/docs/development/test

Install and start MinIO, then configure the mc client and create the required bucket for the S3 storage tests. Run these commands before starting the store tests.

```shell
$ wget https://dl.min.io/server/minio/release/linux-amd64/archive/minio_20230629051228.0.0_amd64.deb -O minio.deb
$ sudo dpkg -i minio.deb
$ mkdir ~/minio
$ minio server ~/minio --console-address :9090 &
$ wget https://dl.min.io/client/mc/release/linux-amd64/mc
$ chmod a+rx mc
$ ./mc alias set myminio http://localhost:9000 minioadmin minioadmin
$ ./mc mb tmp
```

--------------------------------

### Run the installer as root

Source: https://stalw.art/docs/install/platform/linux

Executes the downloaded installation script with root privileges. No arguments are required; the script installs Stalwart under standard Unix paths and starts the daemon.

```bash
$ sudo sh install.sh
```

--------------------------------

### Generated administrator credentials (internal directory)

Source: https://stalw.art/docs/install/platform/docker

Example output shown on the final setup screen when the internal directory is used. The wizard prints an email address and a randomly generated password for the new administrator account. The password is displayed only once and cannot be retrieved from server logs afterwards.

```text
admin@example.com
onMjJfFMO83tQcCX
```

--------------------------------

### Install and run glauth for directory tests

Source: https://stalw.art/docs/development/test

Downloads and runs glauth v2.2.0 for ARM64, then starts it with the LDAP test configuration. Required before running the directory tests.

```shell
$ wget https://github.com/glauth/glauth/releases/download/v2.2.0/glauth-linux-arm64
$ chmod a+rx glauth-linux-arm64
$ ./glauth-linux-arm64 -c tests/resources/ldap.cfg &
```

--------------------------------

### Example /stats response

Source: https://stalw.art/docs/migration/proxy/management/api

Example JSON response from GET /stats showing cache and connection counters.

```json
{
  "cache_hits": 18234,
  "cache_misses": 412,
  "hit_rate_pct": 97.79,
  "cache_entries": 380,
  "active_connections": 27
}

```

--------------------------------

### Import example with --config and --import

Source: https://stalw.art/docs/management/maintenance/migration

Example command to import a previously exported database dump from ~/stalwart-export using the configuration at /opt/stalwart/etc/config.json.

```bash
$ /opt/stalwart/bin/stalwart --config /opt/stalwart/etc/config.json --import ~/stalwart-export
```

--------------------------------

### Access the setup wizard

Source: https://stalw.art/docs/install/platform/docker

Navigate to the setup wizard using the admin interface URL. Replace <hostname> with the server's hostname or IP address.

```text
http://<hostname>:8080/admin
```

--------------------------------

### Install Vandelay via install script (macOS/Linux)

Source: https://stalw.art/docs/migration/import-export/installation

Downloads and runs the official installer, which places the correct binary on the path. The --proto and --tlsv1.2 options enforce a modern, encrypted transport.

```bash
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/stalwartlabs/vandelay/releases/latest/download/vandelay-installer.sh | sh
```

--------------------------------

### Example /mappings response

Source: https://stalw.art/docs/migration/proxy/management/api

Example JSON response from GET /mappings showing how an identifier is resolved.

```json
{
  "identifier": "alice@example.com",
  "normalized": "alice@example.com",
  "destination": "stalwart",
  "routed_to_default": false,
  "cached": true
}

```

--------------------------------

### Start Stalwart with --config

Source: https://stalw.art/docs/configuration

Starts Stalwart with a custom configuration file path. The --config flag is required to point to the startup file that contains the DataStore object.

```bash
stalwart --config /etc/stalwart/config.json
```

--------------------------------

### Mapping file format example

Source: https://stalw.art/docs/migration/proxy/mappings/file

Example mapping file. Each line maps one identifier to one destination, separated by whitespace. Blank lines and lines beginning with `#` are ignored. The destination must be a declared destination; an unknown destination causes the proxy to refuse to start.

```text
# identifier            destination
alice@legacy.example.com    legacy
carol@new.example.com       stalwart
dave@new.example.com        stalwart

```

--------------------------------

### Install script: curl command

Source: https://stalw.art/docs/migration/proxy/installation

Downloads and runs the official install script as root. Requires outbound HTTPS access and either curl or wget. The script installs the binary, service account, service unit, and sample configuration files.

```bash
curl --proto '=https' --tlsv1.2 -sSf \
  https://raw.githubusercontent.com/stalwartlabs/proxy/main/install.sh | sudo sh
```

--------------------------------

### x:Tenant/set - Create tenant

Source: https://stalw.art/docs/ref/object/tenant

Standard JMAP set method to create a tenant. Requires the `sysTenantCreate` permission. The example creates a tenant with name "Example", inherits permissions, empty quotas, and default roles.

```bash
curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:Tenant/set",
          {
            "create": {
              "new1": {
                "name": "Example",
                "permissions": {
                  "@type": "Inherit"
                },
                "quotas": {},
                "roles": {
                  "@type": "Default"
                }
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'
```

--------------------------------

### Start Stalwart service

Source: https://stalw.art/docs/install/platform/windows

Starts the Stalwart service after it has been installed and configured via NSSM.

```powershell
PS> Start-Service Stalwart
```

--------------------------------

### Install stalwart-cli on Windows via PowerShell installer

Source: https://stalw.art/docs/management/cli

Downloads and runs the official PowerShell installer for Windows. Requires PowerShell.

```powershell
powershell -ExecutionPolicy Bypass -c "irm https://github.com/stalwartlabs/cli/releases/latest/download/stalwart-cli-installer.ps1 | iex"
```

--------------------------------

### Fetch the installation script with curl

Source: https://stalw.art/docs/install/platform/linux

Downloads the official Stalwart installation script from get.stalw.art. Requires outgoing HTTPS connectivity.

```bash
$ curl --proto '=https' --tlsv1.2 -sSf https://get.stalw.art/install.sh -o install.sh
```

--------------------------------

### SieveSystemInterpreter configuration example

Source: https://stalw.art/docs/sieve/interpreter/trusted

Configuration example for the SieveSystemInterpreter singleton. Shows how to set default From/Return-Path values, DKIM signing domain, Message-Id hostname, and resource limits such as maxRedirects, maxOutMessages, maxCpuCycles, and duplicateExpiry.

```json
{
  "defaultFromName": {"else": "'Automated Message'"},
  "defaultFromAddress": {"else": "'no-reply@example.org'"},
  "defaultReturnPath": {"else": "''"},
  "messageIdHostname": "mx.example.org",
  "dkimSignDomain": {"else": "system('domain')"},
  "maxRedirects": 3,
  "maxOutMessages": 5,
  "maxReceivedHeaders": 50,
  "maxCpuCycles": 10000,
  "maxNestedIncludes": 5,
  "duplicateExpiry": 604800000
}
```

--------------------------------

### Install the Stalwart Helm chart

Source: https://stalw.art/docs/cluster/orchestration/kubernetes

Installs the Stalwart chart with a custom values file. This is the first step in bootstrapping the deployment.

```bash
helm install stalwart ./stalwart -f values.yaml
```

--------------------------------

### Install Stalwart service with NSSM

Source: https://stalw.art/docs/install/platform/windows

Launches the NSSM graphical installer to create the Stalwart Windows service. Requires nssm.exe in the bin directory.

```powershell
PS> & "C:\Program Files\Stalwart\bin\nssm.exe" install Stalwart
```

--------------------------------

### Run the installer with a custom prefix

Source: https://stalw.art/docs/install/platform/linux

Installs Stalwart under a custom directory (e.g., /opt/stalwart) when the standard FHS paths cannot be used. The script relocates the entire installation under the given prefix.

```bash
$ sudo sh install.sh /opt/stalwart
```

--------------------------------

### Install stalwart-cli on macOS/Linux via shell installer

Source: https://stalw.art/docs/management/cli

Downloads and runs the official installer script for macOS and Linux. Requires curl and a shell.

```bash
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/stalwartlabs/cli/releases/latest/download/stalwart-cli-installer.sh | sh
```

--------------------------------

### Install Rust with rustup

Source: https://stalw.art/docs/development/compile

Command to install Rust on Unix systems using rustup. Follow the onscreen instructions after running.

```bash
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

--------------------------------

### Install Vandelay via npm

Source: https://stalw.art/docs/migration/import-export/installation

Installs the Vandelay binary globally as an npm package.

```bash
npm install -g @stalwartlabs/vandelay
```

--------------------------------

### Install Stalwart with FoundationDB support using --fdb flag

Source: https://stalw.art/docs/install/platform/docker

Run the installation script with the --fdb flag on Linux or macOS to install a build with FoundationDB support. The default build does not include FoundationDB because multiple client versions exist.

```bash
$ sudo sh install.sh --fdb

```

--------------------------------

### Install stalwart-cli via npm

Source: https://stalw.art/docs/management/cli

Installs stalwart-cli globally using npm on any platform with Node.js.

```bash
npm install -g @stalwartlabs/cli
```

--------------------------------

### delete output example

Source: https://stalw.art/docs/management/cli/delete

Example output from a delete command. One line per id, then a summary. Exit status is 0 if all deletions succeed and non-zero if at least one fails.

```text
id1 deleted
id2 deleted
id3 failed: objectIsLinked
  Linked by:   DkimSignature#abc, DkimSignature#def
2 deleted, 1 failed

```

--------------------------------

### key_set example

Source: https://stalw.art/docs/sieve/reference

Stores a value under a key in the default in-memory store, creating it if necessary, and sets an expiration time of 3600 seconds. Returns true on success. This example stops a repeat offender for an hour.

```sieve
eval "key_set('', 'block-${env.remote_ip}', '1', 3600)";
```

--------------------------------

### Example listener configuration for SMTP, submission, and management

Source: https://stalw.art/docs/server/listener

Complete example defining four listeners: SMTP on port 25, explicit-TLS submission on 587, implicit-TLS submissions on 465, and an HTTP management endpoint on 127.0.0.1:8080.

```json
[
  {"name": "smtp", "protocol": "smtp", "bind": {"[::]:25": true}},
  {"name": "submission", "protocol": "smtp", "bind": {"[::]:587": true}},
  {"name": "submissions", "protocol": "smtp", "bind": {"[::]:465": true}, "tlsImplicit": true},
  {"name": "management", "protocol": "http", "bind": {"127.0.0.1:8080": true}}
]
```

--------------------------------

### GET /api/account response example

Source: https://stalw.art/docs/development/api

Example response body for GET /api/account. Shows the effective permissions array, the server edition (oss), and the preferred locale (en-US).

```json
{
  "permissions": [
    "authenticate",
    "jmap-email-get",
    "sys-account-settings-get"
  ],
  "edition": "oss",
  "locale": "en-US"
}
```

--------------------------------

### MX route configuration example

Source: https://stalw.art/docs/mta/outbound/routing

Example JSON configuration for an MX delivery route. Sets maxMxHosts to 3, maxMultihomed to 2, and ipLookupStrategy to v4ThenV6, which tries IPv4 addresses first.

```json
{
  "@type": "Mx",
  "name": "mx",
  "maxMxHosts": 3,
  "maxMultihomed": 2,
  "ipLookupStrategy": "v4ThenV6"
}
```

--------------------------------

### Webhook configuration example with signature and Basic auth

Source: https://stalw.art/docs/telemetry/webhooks

Example webhook configuration for auth.success and store.ingest events with include policy, HMAC signature, custom header, and Basic authentication. Note that wildcard patterns are not supported; each event must be listed explicitly.

```json
{
  "url": "https://example.com/webhook",
  "events": {"auth.success": true, "store.ingest": true},
  "eventsPolicy": "include",
  "timeout": 30000,
  "throttle": 1000,
  "signatureKey": {"@type": "Value", "secret": "my-secret-key"},
  "httpHeaders": {"X-My-Header": "my-value"},
  "httpAuth": {
    "@type": "Basic",
    "username": "account",
    "secret": {"@type": "Value", "secret": "password"}
  },
  "allowInvalidCerts": false,
  "enable": true
}
```

--------------------------------

### Example DKIM TXT record for example.org

Source: https://stalw.art/docs/mta/authentication/dkim/sign

Example DNS TXT record for domain example.org with selector default and RSA public key ABCDEFG.

```text
default._domainkey.example.org. IN TXT "v=DKIM1; k=rsa; p=ABCDEFG"

```

--------------------------------

### Example /destinations response

Source: https://stalw.art/docs/migration/proxy/management/api

Example JSON response from GET /destinations showing a destination entry with failure counters and down state.

```json
{
  "destinations": [
    {
      "destination": "legacy",
      "consecutive_failures": 12,
      "failure_sources": 1,
      "host_level_failure": false,
      "down": false
    }
  ]
}

```

--------------------------------

### SQL Directory Configuration Example

Source: https://stalw.art/docs/auth/backend/sql

Example configuration for the SQL variant of the Directory object. It sets the directory type to Sql, uses the Default store (the server's data store when it is SQL), and maps the database columns name, secret, description, and type to the account fields email, secret, description, and class. The column mappings correspond to the defaults listed in the Column mappings section.

```json
{
  "@type": "Sql",
  "description": "External SQL directory",
  "store": {
    "@type": "Default"
  },
  "columnEmail": "name",
  "columnSecret": "secret",
  "columnDescription": "description",
  "columnClass": "type"
}
```

--------------------------------

### Log file tracer configuration example

Source: https://stalw.art/docs/telemetry/tracing/log

Example JSON configuration for the Log tracer variant. Sets the log directory to /opt/stalwart/logs, prefix to stalwart.log, daily rotation, ANSI colors enabled, multiline disabled, and level info.

```json
{
  "@type": "Log",
  "path": "/opt/stalwart/logs",
  "prefix": "stalwart.log",
  "rotate": "daily",
  "ansi": true,
  "multiline": false,
  "enable": true,
  "level": "info"
}
```

--------------------------------

### Redis GET lookups for mappings

Source: https://stalw.art/docs/migration/proxy/mappings/redis

Example Redis GET lookups showing how the key is formed by concatenating the key_prefix with the normalized identifier. A missing or empty value is treated as absence of a mapping.

```text
GET route:alice@example.com   ->  "legacy"
GET route:carol@example.com   ->  "stalwart"

```

--------------------------------

### x:Bootstrap/get curl request

Source: https://stalw.art/docs/ref/object/bootstrap

Standard Foo/get method for the Bootstrap singleton. Use ids: ["singleton"] or null. Requires sysBootstrapGet permission.

```bash
curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:Bootstrap/get",
          {
            "ids": [
              "singleton"
            ]
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'
```

--------------------------------

### Restart Stalwart container with docker run

Source: https://stalw.art/docs/install/platform/docker

Restart the Stalwart container after completing the setup wizard when the container was started with docker run.

```bash
$ docker restart stalwart
```

--------------------------------

### Query domain ID on new server

Source: https://stalw.art/docs/migration/guide/migrate-accounts

Queries the new server for the domain identifier of the domain 'example.org'. The returned ID is used in subsequent migration commands to reference the existing domain instead of creating it again.

```bash
stalwart-cli query Domain --where name=example.org --fields id
```

--------------------------------

### Promote configuration across environments with snapshot and apply

Source: https://stalw.art/docs/management/cli/snapshot

Promotes configuration from staging to production. The plan reconciles selected types: existing objects are updated, missing ones are created, and nothing is destroyed. Use --dry-run on apply in CI to review the plan before it takes effect.

```bash
# On staging
stalwart-cli --url https://staging.mail.example.com \
    snapshot Tenant Domain ... --output plan.ndjson


# On production
stalwart-cli --url https://prod.mail.example.com \
    apply --file plan.ndjson
```

--------------------------------

### detect_file_type: reject executable by extension

Source: https://stalw.art/docs/sieve/reference

Inline example in the detect_file_type section. Uses content sniffing to get the file extension and discards the message when it is 'exe'.

```text
if eval "detect_file_type('ext') == 'exe'" { discard; }
```

--------------------------------

### Run stalwart-cli Docker with environment variables for query and apply

Source: https://stalw.art/docs/management/cli

Shows how to pass connection settings via environment variables and bind-mount a working directory for commands that read or write files.

```bash
docker run --rm \
  -e STALWART_URL=https://mail.example.com \
  -e STALWART_TOKEN \
  ghcr.io/stalwartlabs/cli query Account --fields id,name
```

```bash
docker run --rm \
  -v "$PWD:/work" -w /work \
  -e STALWART_URL -e STALWART_TOKEN \
  ghcr.io/stalwartlabs/cli apply --file plan.json
```

--------------------------------

### Fetch emails with stalwart-cli get Email

Source: https://stalw.art/docs/ref/object/email

Fetches email data using the stalwart-cli, which wraps the same JMAP calls. Requires installation and authentication as described in the CLI reference.

```bash
stalwart-cli get Email
```

--------------------------------

### List encoding for retry intervals

Source: https://stalw.art/docs/configuration/object-encoding

Example of an ordered list encoded as a JSON object with stringified keys starting at "0". The keys determine evaluation order.

```json
{
  "intervals": {
    "0": {"duration": 120000},
    "1": {"duration": 300000}
  }
}
```

--------------------------------

### Create a Tenant with stalwart-cli

Source: https://stalw.art/docs/ref/object/tenant

Creates a new tenant with a name, default role, inherited permissions, and empty quotas.

```bash
stalwart-cli create Tenant \
  --field name=Example \
  --field 'roles={"@type":"Default"}' \
  --field 'permissions={"@type":"Inherit"}' \
  --field 'quotas={}'
```

--------------------------------

### x:DmarcInternalReport/get - Fetch report by ID

Source: https://stalw.art/docs/ref/object/dmarc-internal-report

Standard JMAP get method (RFC 8620, Section 5.1). Requires the sysDmarcInternalReportGet permission. The example fetches the report with id 'id1'.

```bash
curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:DmarcInternalReport/get",
          {
            "ids": [
              "id1"
            ]
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'
```

--------------------------------

### stalwart-cli create synopsis

Source: https://stalw.art/docs/management/cli/create

Shows the general syntax for the create command. The four input forms are mutually exclusive; supplying more than one raises an error.

```bash
stalwart-cli create <object> ( --field key=value... | --json '<json>' | --file <path> | --stdin )
```

--------------------------------

### x:Metric/get - Retrieve metrics

Source: https://stalw.art/docs/ref/object/metric

Standard JMAP get method (RFC 8620, Section 5.1). Requires the `sysMetricGet` permission. The example requests a metric with id "id1".

```bash
curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:Metric/get",
          {
            "ids": [
              "id1"
            ]
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'
```

--------------------------------

### Fetch AccountSettings via stalwart-cli

Source: https://stalw.art/docs/ref/object/account-settings

Fetches the AccountSettings singleton using the stalwart-cli command-line tool.

```bash
stalwart-cli get AccountSettings
```

--------------------------------

### x:Tenant/get - Fetch tenant by ID

Source: https://stalw.art/docs/ref/object/tenant

Standard JMAP get method to retrieve a tenant by ID. Requires the `sysTenantGet` permission. The example uses `ids: ["id1"]` and includes the required capabilities `urn:ietf:params:jmap:core` and `urn:stalwart:jmap`.

```bash
curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:Tenant/get",
          {
            "ids": [
              "id1"
            ]
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'
```

--------------------------------

### Stalwart Helm chart values.yaml

Source: https://stalw.art/docs/cluster/orchestration/kubernetes

Complete values.yaml for the Stalwart Kubernetes chart. Edit this file to configure the deployment: set image, replica count, role, recovery admin, service type, ingress, persistence, and security contexts. The example shows defaults for a single-node install with RocksDB storage and ClusterIP service.

```yaml
# Container image.
image:
  repository: stalwartlabs/stalwart
  tag: "v0.16"
  pullPolicy: IfNotPresent


# Number of pods in the StatefulSet.
# Single-node deployments keep this at 1.
# For a clustered deployment, raise this value and set `role` (and
# `pushShard` where applicable) to a value that makes sense for the
# whole StatefulSet, or install multiple releases of this chart with
# different role values.
replicaCount: 1


# Maps to STALWART_ROLE. Names a ClusterRole defined in the database.
# Leave empty on single-node installs to run every task and listener.
# See /docs/cluster/configuration/roles for the role model.
role: ""


# Maps to STALWART_PUSH_SHARD. Only set on nodes whose role delivers
# push notifications. Leave empty on single-node installs.
pushShard: ""


# Recovery / bootstrap administrator credential.
# Enable this on first install so the operator can sign in without
# scraping the pod logs for the generated temporary password.
# Remove it once a permanent administrator account has been
# provisioned through the setup wizard.
recoveryAdmin:
  enabled: true
  username: admin
  password: "change-me"


# Starts the pods in recovery mode. Suspends mail services and
# exposes only the management listener on the configured port.
# See /docs/configuration/recovery-mode.
recoveryMode:
  enabled: false
  port: 8080
  logLevel: info


# Extra environment variables injected into the container, for
# store credentials that live in plain text.
extraEnv: {}


# Extra environment variables injected from the managed Secret.
# Use this for anything sensitive (database passwords, S3 keys, etc.).
extraSecretEnv: {}


# config.json contents. Rendered verbatim into the ConfigMap.
# Only the DataStore object belongs here; every other setting lives
# in the database once the server is bootstrapped.
# See /docs/configuration/overview and /docs/ref/object/data-store.
config:
  "@type": RocksDb
  path: /var/lib/stalwart


# Service definition. Change `type` to LoadBalancer when a cloud
# load balancer should expose the mail ports directly, or keep it
# as ClusterIP and front the chart with an Ingress / gateway for
# the HTTP listeners only.
service:
  type: ClusterIP
  ports:
    smtp: 25
    smtps: 465
    submission: 587
    imap: 143
    imaps: 993
    pop3: 110
    pop3s: 995
    sieve: 4190
    http: 80
    https: 443
    mgmt: 8080


# Ingress for the HTTP / HTTPS listeners only. Mail protocols
# require L4 exposure and are not handled here.
ingress:
  enabled: false
  className: nginx
  annotations: {}
  hosts:
    - host: mail.example.org
      paths:
        - path: /
          pathType: Prefix
          portName: https
  tls: []


# Persistent volume for the data directory. Required when the
# DataStore is a local backend such as RocksDB. Can be disabled
# for deployments that use an external store (PostgreSQL, MySQL,
# FoundationDB, S3-backed blob store, etc.).
persistence:
  enabled: true
  accessMode: ReadWriteOnce
  storageClass: ""
  size: 20Gi


# Resource requests and limits for the container.
resources: {}


# Pod-level security context. Applied to every container in the pod.
# The defaults are sufficient for the `baseline` Pod Security Standard.
# See "Restricted Pod Security Standards" below for the override
# required under the `restricted` profile.
podSecurityContext:
  fsGroup: 2000
  runAsUser: 2000
  runAsGroup: 2000


# Container-level security context for the stalwart container.
# Empty by default. Set this to opt into the `restricted` Pod Security
# Standard; see "Restricted Pod Security Standards" below.
containerSecurityContext: {}
```

--------------------------------

### Create a user account with stalwart-cli create

Source: https://stalw.art/docs/ref/object/account

Creates a new user account with the specified fields, including credentials, roles, permissions, and encryption settings.

```bash
stalwart-cli create Account/User \
  --field name=alice \
  --field 'domainId=<Domain id>' \
  --field 'credentials={}' \
  --field 'memberGroupIds={}' \
  --field 'roles={"@type":"User"}' \
  --field 'permissions={"@type":"Inherit"}' \
  --field 'quotas={}' \
  --field 'aliases={}' \
  --field 'encryptionAtRest={"@type":"Disabled"}'
```

--------------------------------

### Verify stalwart-cli installation

Source: https://stalw.art/docs/management/cli

Checks that the CLI is installed and displays its version.

```bash
stalwart-cli --version
```

--------------------------------

### x:Domain/set - Create domain

Source: https://stalw.art/docs/ref/object/domain

Creates a new domain with specified properties. Requires the `sysDomainCreate` permission. The example sets aliases, certificate management, DKIM management, DNS management, name, and sub-addressing.

```bash
curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:Domain/set",
          {
            "create": {
              "new1": {
                "aliases": {},
                "certificateManagement": {
                  "@type": "Manual"
                },
                "dkimManagement": {
                  "@type": "Automatic"
                },
                "dnsManagement": {
                  "@type": "Manual"
                },
                "name": "example.com",
                "subAddressing": {
                  "@type": "Enabled"
                }
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'
```

--------------------------------

### Install stalwart-cli via Homebrew

Source: https://stalw.art/docs/management/cli

Installs stalwart-cli using Homebrew on macOS or Linux.

```bash
brew install stalwartlabs/tap/stalwart-cli
```

--------------------------------

### stalwart-cli create

Source: https://stalw.art/docs/management/cli/create

Documentation for the `stalwart-cli create` command, including its synopsis, options, and examples for multi-variant objects.

```APIDOC
## stalwart-cli create

### Description
Creates a single object from one of four input sources. Validation is minimal; the CLI only checks that field names exist on the schema and that values are of the right shape.

### Method
CLI command

### Endpoint
`stalwart-cli create <object> ( --field key=value... | --json '<json>' | --file <path> | --stdin )`

### Parameters
#### Positional Arguments
- **<object>** (string) - Required - Object type name (with or without `x:` prefix). For multi-variant objects, use the `Object/Variant` shorthand to select a variant.

#### Options
- **--field** (key=value) - Optional - Provide field values as key=value pairs. Mutually exclusive with other input forms.
- **--json** (string) - Optional - Provide the object as a JSON string. Mutually exclusive with other input forms.
- **--file** (path) - Optional - Provide the object from a file. Mutually exclusive with other input forms.
- **--stdin** (flag) - Optional - Provide the object from standard input. Mutually exclusive with other input forms.

### Notes
- The four input forms are mutually exclusive; an error is raised if more than one is supplied.
- Multi-variant objects require an `@type` value. Use the `Object/Variant` shorthand or supply `@type` directly.
- If both the slash form and an explicit `@type` are supplied, the user's value wins and a warning is printed.

### Examples
#### Slash shorthand
```
stalwart-cli create account/user \
  --field name=alice \
  --field domainId=b \
  --field 'credentials={"0":{"@type":"Password","secret":"hunter2"}}'
```

#### Explicit @type
```
stalwart-cli create account \
  --field @type=User \
  --field name=alice \
  --field domainId=b
```
```

--------------------------------

### Run proxy binary with configuration file

Source: https://stalw.art/docs/migration/proxy/installation

Run the proxy binary directly, passing the path to its configuration file as the first argument. Alternatively, the path can be provided via the PROXY_CONFIG environment variable.

```bash
proxy /etc/proxy/config.toml
```

--------------------------------

### Apply migration plan on new server

Source: https://stalw.art/docs/migration/guide/migrate-accounts

Applies the migration plan 'alice-plan.ndjson' to the new server using the 'stalwart-cli apply' command. This creates the account on the new server.

```bash
admin_route new
stalwart-cli apply --file alice-plan.ndjson
```

--------------------------------

### List all management objects with stalwart-cli describe

Source: https://stalw.art/docs/management/cli/describe

Run `stalwart-cli describe` with no arguments to list all management objects in sorted order. The output includes a table of object names and descriptions, with `[singleton]` tags marking objects that have exactly one instance per server and cannot be created or destroyed.

```bash
stalwart-cli describe
```

```text
Account                 Defines a user or group account for authentication and email access.
AccountPassword         Password-based authentication credential. [singleton]
AccountSettings         Configures default account settings for locale and encryption. [singleton]
AcmeProvider            Defines an ACME provider for automatic TLS certificate management.
Action                  Defines server management actions such as reloads, troubleshooting and cache operations.
AddressBook             Configures address book and contact storage settings. [singleton]
...
Domain                  Defines an email domain and its DNS, DKIM, and TLS certificate settings.
...
SystemSettings          Server-wide configuration. [singleton]
...
```

--------------------------------

### stalwart-cli get MtaOutboundThrottle

Source: https://stalw.art/docs/ref/object/mta-outbound-throttle

Fetches a MtaOutboundThrottle object by its ID using the stalwart-cli get command.

```APIDOC
## stalwart-cli get MtaOutboundThrottle

### Description
Fetches a MtaOutboundThrottle object by its ID using the stalwart-cli get command.

### Command
`stalwart-cli get MtaOutboundThrottle id1`

### Parameters
- **id** (string) - Required - The ID of the throttle to fetch.

### Example
```
stalwart-cli get MtaOutboundThrottle id1
```
```

--------------------------------

### stalwart-cli get Certificate

Source: https://stalw.art/docs/ref/object/certificate

Fetches a Certificate object by its ID using the stalwart-cli get command.

```APIDOC
## GET Certificate

### Description
Fetches a Certificate object by its ID.

### Method
GET

### Endpoint
stalwart-cli get Certificate {id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the Certificate to fetch.

### Request Example
```
stalwart-cli get Certificate id1
```

### Response
Returns the Certificate object with the specified ID.
```

--------------------------------

### Create an API key with stalwart-cli

Source: https://stalw.art/docs/ref/object/api-key

Creates a new API key with a description, inherited permissions, and an empty allowed IPs list.

```bash
stalwart-cli create ApiKey \
  --field description=Example \
  --field 'permissions={"@type":"Inherit"}' \
  --field 'allowedIps={}'
```

--------------------------------

### stalwart-cli get ArchivedItem id1

Source: https://stalw.art/docs/ref/object/archived-item

Fetches an archived item by its ID using the `get` command.

```APIDOC
## stalwart-cli get ArchivedItem id1

### Description
Fetches an archived item by its ID using the `get` command.

### Command
`stalwart-cli get ArchivedItem id1`

### Arguments
- **id1** (string) - Required - The ID of the archived item to fetch.

### Example
```
stalwart-cli get ArchivedItem id1
```
```

--------------------------------

### Create an LDAP directory with stalwart-cli create

Source: https://stalw.art/docs/ref/object/directory

Creates an LDAP directory with description, baseDn, and a bindSecret of type None.

```bash
stalwart-cli create Directory/Ldap \
  --field description=Example \
  --field baseDn=Example \
  --field 'bindSecret={"@type":"None"}'
```

--------------------------------

### EHLO stage configuration example

Source: https://stalw.art/docs/mta/inbound/ehlo

Configures the MtaStageEhlo singleton with require, rejectNonFqdn, and script fields. Includes a per-listener override for rejectNonFqdn and a Sieve script selector.

```json
{
  "require": {"else": "true"},
  "rejectNonFqdn": {
    "match": {"0": {"if": "listener == 'smtp'", "then": "true"}},
    "else": "false"
  },
  "script": {"else": "'ehlo'"}
}
```

--------------------------------

### stalwart-cli get PublicKey id1

Source: https://stalw.art/docs/ref/object/public-key

Fetches a PublicKey object by its identifier using the stalwart-cli get command.

```APIDOC
## stalwart-cli get PublicKey id1

### Description
Fetches a PublicKey object by its identifier.

### Command
`stalwart-cli get PublicKey id1`

### Arguments
- **id** (string) - Required - The identifier of the PublicKey to fetch.

```

--------------------------------

### Fetch SearchStore with stalwart-cli

Source: https://stalw.art/docs/ref/object/search-store

Fetches the SearchStore configuration using the stalwart-cli command-line tool.

```bash
stalwart-cli get SearchStore
```

--------------------------------

### stalwart-cli get Role id1

Source: https://stalw.art/docs/ref/object/role

Fetches a Role object by its identifier using the stalwart-cli get command.

```APIDOC
## stalwart-cli get Role id1

### Description
Fetches a Role object by its identifier.

### Command
`stalwart-cli get Role id1`

### Arguments
- **Role** (string) - The object type to fetch.
- **id1** (string) - The identifier of the Role to fetch.

### Example
```
stalwart-cli get Role id1
```
```

--------------------------------

### stalwart-cli get AddressBook

Source: https://stalw.art/docs/ref/object/address-book

CLI command to fetch the AddressBook singleton. Wraps the JMAP get call.

```bash
stalwart-cli get AddressBook
```

--------------------------------

### stalwart-cli apply synopsis

Source: https://stalw.art/docs/management/cli/apply

Shows the command-line syntax for the apply command. Exactly one of --file or --stdin must be supplied. Options include --dry-run, --continue-on-error, --quiet, --json, and --progress.

```text
stalwart-cli apply ( --file <path> | --stdin )
                   [--dry-run]
                   [--continue-on-error]
                   [--quiet]
                   [--json]
                   [--progress]

```

--------------------------------

### Import managesieve with basic auth and STARTTLS

Source: https://stalw.art/docs/migration/import-export/import/managesieve

Imports Sieve scripts from a generic provider (e.g., Fastmail) using basic authentication over sieve:// with a STARTTLS upgrade. The password is prompted interactively.

```bash
vandelay import managesieve \
  --url sieve://sieve.example.net \
  --auth-basic alice@example.net \
  alice.sqlite
```

--------------------------------

### Install Vandelay via PowerShell (Windows)

Source: https://stalw.art/docs/migration/import-export/installation

Runs the equivalent install script through PowerShell with execution policy bypass.

```powershell
powershell -ExecutionPolicy Bypass -c "irm https://github.com/stalwartlabs/vandelay/releases/latest/download/vandelay-installer.ps1 | iex"
```

--------------------------------

### Create a domain with stalwart-cli create

Source: https://stalw.art/docs/ref/object/domain

Creates a new domain with the specified fields, including manual certificate and DNS management, automatic DKIM management, and enabled subaddressing.

```bash
stalwart-cli create Domain \
  --field name=example.com \
  --field 'aliases={}' \
  --field 'certificateManagement={"@type":"Manual"}' \
  --field 'dkimManagement={"@type":"Automatic"}' \
  --field 'dnsManagement={"@type":"Manual"}' \
  --field 'subAddressing={"@type":"Enabled"}'
```

--------------------------------

### Install JMAP TestSuite Perl dependencies

Source: https://stalw.art/docs/development/test

Installs the recommended Perl dependencies for the JMAP TestSuite using cpanm.

```shell
cpanm --installdeps .
```

--------------------------------

### stalwart-cli get MemoryLookupKeyValue

Source: https://stalw.art/docs/ref/object/memory-lookup-key-value

Fetches a MemoryLookupKeyValue object by its ID using the CLI. This wraps the JMAP get call.

```APIDOC
## stalwart-cli get MemoryLookupKeyValue

### Description
Fetches a MemoryLookupKeyValue object by its ID using the CLI.

### Method
CLI

### Endpoint
stalwart-cli get MemoryLookupKeyValue id1

### Parameters
- **id** (string) - Required - The ID of the object to fetch.

### Request Example
```bash
stalwart-cli get MemoryLookupKeyValue id1
```
```

--------------------------------

### Create a domain with stalwart-cli

Source: https://stalw.art/docs/migration/guide/configure-new

Creates a domain on the new deployment before migrating accounts or enabling split delivery. The domain must exist on the new server before accounts can be migrated or recognized as local. Creating the domain does not divert mail to the new server; mail continues to reach the source until the proxy is started.

```bash
stalwart-cli create Domain --field name=example.org
```

--------------------------------

### stalwart-cli get DnsServer id1

Source: https://stalw.art/docs/ref/object/dns-server

Fetches a DNS server record by its ID using the stalwart-cli get command.

```APIDOC
## stalwart-cli get DnsServer id1

### Description
Fetches a DNS server record by its ID.

### Command
`stalwart-cli get DnsServer id1`

### Parameters
- **id** (string) - Required - The ID of the DNS server to fetch.

### Example
```
stalwart-cli get DnsServer id1
```

```

--------------------------------

### get command synopsis

Source: https://stalw.art/docs/management/cli/get

Shows the command-line syntax for the get command. The <object> argument is the object type name, with or without the x: prefix, case-insensitive. <id> is required for normal objects but optional for singletons, defaulting to singleton. The --fields option takes a comma-separated list of properties to fetch, and --json emits a single-line JSON document instead of the human-friendly view.

```bash
stalwart-cli get <object> [<id>] [--fields name,email,...] [--json]
```

--------------------------------

### Install Vandelay via Homebrew

Source: https://stalw.art/docs/migration/import-export/installation

Installs Vandelay from the Stalwart tap. Future upgrades are handled with the usual brew upgrade.

```bash
brew install stalwartlabs/tap/vandelay
```

--------------------------------

### Create API key with x:ApiKey/set

Source: https://stalw.art/docs/ref/object/api-key

Creates a new API key with an empty allowed IP set, a description, and inherited permissions. Requires the `sysApiKeyCreate` permission.

```bash
curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:ApiKey/set",
          {
            "create": {
              "new1": {
                "allowedIps": {},
                "description": "Example",
                "permissions": {
                  "@type": "Inherit"
                }
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'
```

--------------------------------

### Create an Application with stalwart-cli

Source: https://stalw.art/docs/ref/object/application

Creates an Application object with the specified fields. The urlPrefix field is set to '{}'.

```bash
stalwart-cli create Application \
  --field description=Example \
  --field resourceUrl=Example \
  --field 'urlPrefix={}'
```

--------------------------------

### Fetch Cache object with stalwart-cli get

Source: https://stalw.art/docs/ref/object/cache

Retrieves the current Cache object configuration. The command is `stalwart-cli get Cache`.

```bash
stalwart-cli get Cache
```

--------------------------------

### Get TlsInternalReport with x:TlsInternalReport/get

Source: https://stalw.art/docs/ref/object/tls-internal-report

Retrieves a TlsInternalReport object by ID using the JMAP get method. Requires the sysTlsInternalReportGet permission.

```bash
curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:TlsInternalReport/get",
          {
            "ids": [
              "id1"
            ]
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'
```

--------------------------------

### Create a WebHook with stalwart-cli create

Source: https://stalw.art/docs/ref/object/web-hook

Creates a WebHook with no signature, no authentication, empty headers, and no events.

```bash
stalwart-cli create WebHook \
  --field 'signatureKey={"@type":"None"}' \
  --field url=https://example.com \
  --field 'httpAuth={"@type":"Unauthenticated"}' \
  --field 'httpHeaders={}' \
  --field 'events={}'
```

--------------------------------

### Get MtaQueueQuota via JMAP

Source: https://stalw.art/docs/ref/object/mta-queue-quota

Retrieves MtaQueueQuota objects by ID using the JMAP get method. Requires the sysMtaQueueQuotaGet permission.

```bash
curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:MtaQueueQuota/get",
          {
            "ids": [
              "id1"
            ]
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'
```

--------------------------------

### Error response JSON example

Source: https://stalw.art/docs/development/api

Example of an RFC 7807 problem+json error response body, shown for a 401 Unauthorized error.

```json
{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing credentials."
}
```

--------------------------------

### CLI fetch SpamSettings

Source: https://stalw.art/docs/ref/object/spam-settings

Fetches the SpamSettings singleton using the `stalwart-cli` command. Wraps the same JMAP call.

```bash
stalwart-cli get SpamSettings
```

--------------------------------

### Start Stalwart test instance for IMAP4 compliance

Source: https://stalw.art/docs/development/test

Starts a Stalwart instance using the test configuration file for IMAP4 compliance testing.

```shell
$ cargo run --manifest-path=crates/main/Cargo.toml -- --config=./tests/resources/test_config.json
```

--------------------------------

### Launch the database console with --console and --config

Source: https://stalw.art/docs/management/maintenance/database

Starts the Stalwart database console using the specified configuration file. The console can run concurrently with a running server for FoundationDB, PostgreSQL, or MySQL backends, but the server must be stopped for embedded databases like RocksDB or SQLite.

```bash
$ /opt/stalwart/bin/stalwart --config /opt/stalwart/etc/config.json --console
```
Tokens:
Raw