### Pyzor Configuration Example

Source: https://stalw.art/docs/spamfilter/digests

This JSON object shows an example configuration for Pyzor, matching the default public server settings. Adjust 'host', 'port', and 'timeout' for custom setups.

```json
{
  "enable": true,
  "host": "public.pyzor.org",
  "port": 24441,
  "timeout": "5s",
  "blockCount": 5,
  "allowCount": 10,
  "ratio": 0.2
}
```

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

### NixOS Configuration Example

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

Example of how to configure the stalwart-bootstrap service in a NixOS configuration.

```nix
services.stalwart-bootstrap = {
  enable = true;
  url = "https://mail.example.com";
  credentialsFile = "/run/secrets/stalwart-admin";
  plan = [
    { "@type" = "upsert";
      object  = "Domain";
      matchOn = [ "name" ];
      value   = { dom-a = { name = "example.com"; }; };
    }
    { "@type" = "update";
      object  = "SystemSettings";
      value   = { defaultDomainId = "#dom-a"; defaultHostname = "mail.example.com"; };
    }
  ];
};

```

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

### Mapping File Example for Dovecot/Postfix

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

Initial content for the mapping file when migrating from Dovecot/Postfix. The file starts empty as the source does not serve a web interface requiring initial routing.

```text

```

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

### Start Stalwart Test Instance

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

Use this command to start a test instance of Stalwart. Ensure you have the correct manifest path.

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

```

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

### Start Stalwart with Configuration File

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

Specify the path to the config.json file using the --config flag when starting the Stalwart server.

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

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

### Start Stalwart Service

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

Starts the Stalwart service after it has been installed.

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

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

### Run Stalwart Installation Script

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

Executes the downloaded installation script with root privileges. This installs Stalwart to standard Unix paths.

```bash
$ sudo sh install.sh

```

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

### Access Stalwart Setup Wizard

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

Once you have the administrator credentials (either temporary or fixed), open a web browser to access the Stalwart setup wizard. Replace `<hostname>` with your server's address. For local access, `127.0.0.1` can be used.

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

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

### Install Stalwart Proxy using curl and sh

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

Download and execute the Stalwart Proxy installation script using curl. This script requires root privileges and installs the proxy binary and associated configuration files.

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

```

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

### Fetch Tracing Store via CLI

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

Use the `stalwart-cli get` command to fetch tracing store data. Ensure you have the CLI installed and authenticated.

```bash
stalwart-cli get TracingStore
```

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

### Install Stalwart with FoundationDB Support on Linux

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

Run the installation script with the --fdb flag to include FoundationDB support. This is necessary for installations using FoundationDB as the main data store.

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

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

### Webhook Configuration Example

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

An example configuration for a webhook, specifying the URL, events to include, authentication, custom headers, and other delivery settings.

```json
{
  "url": "https://example.com/webhook",
  "events": ["auth.success", "store.ingest"],
  "eventsPolicy": "include",
  "timeout": "30s",
  "throttle": "1s",
  "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
}
```

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

### Build and Install Stalwart CLI from Source

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

Builds the stalwart-cli from source using Cargo and installs it. Requires a recent Rust toolchain and Git.

```shell
git clone https://github.com/stalwartlabs/cli.git
cd cli
cargo install --path .
```

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

### Install Vandelay using Script (macOS/Linux)

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

Installs Vandelay by downloading the correct binary for your host platform and architecture. Ensures download over encrypted transport.

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

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

### OIDC Directory Configuration Example

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

Example configuration for an OIDC integration with a Keycloak-style provider. This defines how Stalwart should interact with the identity provider to authenticate users.

```json
{
  "@type": "Oidc",
  "description": "External IdP",
  "issuerUrl": "https://accounts.example.org/realms/myrealm",
  "requireAudience": "stalwart",
  "requireScopes": ["openid", "email"],
  "claimUsername": "preferred_username",
  "usernameDomain": "example.org",
  "claimName": "name",
  "claimGroups": "groups"
}
```

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

### Webhook Configuration Example

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

This example demonstrates how to configure a webhook to send notifications for 'auth.success' and 'store.ingest' events. It includes settings for signature key, custom HTTP headers, and Basic authentication.

```APIDOC
## Webhook Configuration Example

### Description
This example shows a webhook configuration that sends notifications for specific events, includes a signature key for security, custom HTTP headers, and Basic authentication.

### Method
POST (Implicit, as webhooks send data to an endpoint)

### Endpoint
`https://example.com/webhook` (This is the `url` field in the configuration)

### Parameters
#### Request Body Fields
- **url** (string) - Required - The endpoint to which POST requests are sent.
- **events** (array of strings) - Required - List of events that trigger the webhook.
- **eventsPolicy** (string) - Required - Policy for interpreting the `events` list ('include' or 'exclude').
- **timeout** (string) - Optional - Maximum time to wait for a response. Default is "30s".
- **throttle** (string) - Optional - Minimum interval between batches. Default is "1s".
- **signatureKey** (object) - Optional - HMAC key used to sign request bodies. Can be `None`, `Value`, `EnvironmentVariable`, or `File`.
  - **@type** (string) - Specifies the type of secret key.
  - **secret** (string) - The actual secret key value when `@type` is `Value`.
- **httpHeaders** (object) - Optional - Additional HTTP headers to include in requests.
  - **X-My-Header** (string) - Example custom header.
- **httpAuth** (object) - Optional - HTTP authentication method.
  - **@type** (string) - Specifies the authentication type ('Unauthenticated', 'Basic', 'Bearer').
  - **username** (string) - Required if `@type` is 'Basic'.
  - **secret** (object) - Required if `@type` is 'Basic'.
    - **@type** (string) - Specifies the type of secret.
    - **secret** (string) - The actual password value when `@type` is `Value`.
- **allowInvalidCerts** (boolean) - Optional - Whether to permit requests to endpoints with invalid TLS certificates. Default is `false`.
- **enable** (boolean) - Optional - Whether the webhook is active. Default is `true`.

### Request Example
```json
{
  "url": "https://example.com/webhook",
  "events": ["auth.success", "store.ingest"],
  "eventsPolicy": "include",
  "timeout": "30s",
  "throttle": "1s",
  "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
}
```

### Response
#### Success Response (200)
- **events** (array of WebhookEvent objects) - A list of events delivered.

#### Response Example
```json
{
    "events": [
        {
            "id": "12345",
            "createdAt": "2023-06-21T14:55:00Z",
            "type": "auth.success",
            "data": {}
        }
    ]
}
```

### Event Object Structure
Each `WebhookEvent` object contains:
- **id** (String): Unique identifier for the event.
- **createdAt** (RFC3339 timestamp): Timestamp when the event was created.
- **type** (WebhookType): Type of the event.
- **data** (WebhookPayload): Detailed data associated with the event. The structure varies by event type.
```

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

### Fetch InMemoryStore Data

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

Use this command to retrieve all data currently stored in the InMemoryStore. No specific setup is required beyond having the stalwart-cli installed.

```bash
stalwart-cli get InMemoryStore
```

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

### Import Database Dump

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

Initiate an import by running the Stalwart binary with the --import argument pointing to the database dump directory. Use --config to specify the configuration file for the new backend.

```bash
$ /opt/stalwart/bin/stalwart --config /path/to/config.json --import /path/to/export-directory
```

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

### Mapping File Format Example

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

Define mappings between identifiers and destinations in a tab-separated or space-separated file. Blank lines and lines starting with '#' are ignored. Ensure destinations are valid.

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

```

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

### Basic Create Command Synopsis

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

This is the general synopsis for the `create` command, outlining the available object types and input methods.

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

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

### Retrieve Stalwart Bootstrap Credentials

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

After the container starts, Stalwart enters bootstrap mode and generates temporary administrator credentials. View the container logs to find these credentials, which are needed for the initial setup. This is the only time the temporary password will be visible.

```bash
$ docker logs stalwart 2>&1 | grep -A8 'bootstrap mode'
```

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

### Connect to Server with Environment Variables

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

Connect to a Stalwart server using environment variables for URL, username, and password. Recommended for scripts and CI.

```bash
export STALWART_URL=https://mail.example.com
export STALWART_USER=admin
export STALWART_PASSWORD='changeme'
stalwart-cli describe
```

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

### CLI Pagination Example

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

Demonstrates the interactive pagination prompt when stdout is a TTY. Press 'y' or Enter to show more results, 'n' to stop.

```bash
... 10 rows ...
Show more? [Y/n] y
... next 10 rows ...
```

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

### Install Stalwart CLI via PowerShell (Windows)

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

Installs the stalwart-cli on Windows using PowerShell to download and execute an installer script. The ExecutionPolicy is bypassed for the installation.

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

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

### Connect to Local Server with Credentials

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

Connect to a local Stalwart development server using URL, username, and password flags.

```bash
stalwart-cli --url http://localhost:8080 --user admin --password admin describe
```

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

### Install Vandelay using PowerShell (Windows)

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

Installs Vandelay on Windows using a PowerShell script. Bypasses execution policy for installation.

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

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

### Account Mapping File Example

Source: https://stalw.art/docs/migration/proxy/examples/stalwart-upgrade

Lists migrated accounts, mapping both bare usernames and full email addresses to the new deployment to ensure consistent login resolution.

```text
alice@example.org   new
alice               new

```

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

### Install Stalwart CLI via npm (Node.js)

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

Installs the stalwart-cli globally using npm, making it available on all platforms where Node.js is installed.

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

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

### Display General Help

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

Use the --help flag to display general help information for the Stalwart CLI.

```bash
stalwart-cli --help
```

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

### Download Stalwart Installation Script

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

Fetches the latest Stalwart installation script using curl. Ensure you have curl installed and outgoing HTTPS connectivity.

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

```

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

### Install Stalwart CLI via Shell Script (macOS/Linux)

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

Installs the stalwart-cli using a curl command to download and execute an installer script. This is suitable for macOS and Linux systems.

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

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

### List all management objects

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

Run `describe` with no arguments to get a sorted list of all management objects. The output includes a brief description for each object, with `[singleton]` indicating objects with a single instance per server.

```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]
...
```

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

### Promote Configuration Between Environments

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

This snippet shows how to create a snapshot plan on a staging environment and then apply it to a production environment. The `apply` command reconciles configurations, updating existing objects and creating new ones without destroying existing production data. Use `--dry-run` for review before applying.

```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
```

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

### Run Stalwart Installation Script with Custom Prefix

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

Executes the installation script with root privileges, specifying a custom directory prefix for the installation. This is useful when standard FHS paths are not suitable.

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

```

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

### Display Help Information

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

Type 'help' to display a list of all available commands and usage hints within the database console.

```bash
help
```

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

### Verify Stalwart CLI Installation

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

Verifies that the stalwart-cli has been installed correctly by checking its version.

```shell
stalwart-cli --version
```

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

### Launch Stalwart Database Console

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

Run the Stalwart binary with the --config and --console parameters to launch the database console. Ensure the --config path points to your Stalwart configuration file.

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

```

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

### Create Tenant using CLI

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

Use the `stalwart-cli create Tenant` command to provision a new tenant, specifying fields using `--field` arguments.

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

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

### Verify Vandelay Installation

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

Confirms that Vandelay is installed and accessible on the system's PATH by checking its version.

```bash
vandelay --version
```

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

### Fetch SearchStore using stalwart-cli

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

Retrieve the SearchStore configuration using the `stalwart-cli` command-line tool.

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

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

### Install Vandelay using npm

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

Installs Vandelay globally as an npm package for environments managing tooling through Node.js.

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

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

### Statistics Response Example

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

Example JSON response for the `/stats` endpoint, showing cache performance and connection counts.

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

```

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

### Fetch DataStore using stalwart-cli

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

Command-line interface command to fetch the DataStore. Ensure the `stalwart-cli` is installed and authenticated.

```bash
stalwart-cli get DataStore
```

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

### Fetch DataStore (CLI)

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

Fetches the DataStore configuration using the `stalwart-cli` command-line tool.

```APIDOC
## Fetch DataStore

### Description
Fetches the DataStore configuration using the `stalwart-cli` command-line tool.

### Command
```bash
stalwart-cli get DataStore
```
```

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

### Install Stalwart CLI via Homebrew (macOS/Linux)

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

Installs the stalwart-cli on macOS and Linux systems that use Homebrew package manager.

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

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

### Install Stalwart Service with NSSM

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

Installs Stalwart as a Windows service using NSSM. This command should be run from an elevated PowerShell window.

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

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

### Redis Key Layout Example

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

Illustrates how mapping identifiers are translated into Redis keys using the configured key prefix.

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

```

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

### Configure Form Handling

Source: https://stalw.art/docs/http/form-submission

Example configuration for the HttpForm singleton. Adjust fields like enable, maxSize, rateLimit, deliverTo, and various field names to customize behavior.

```json
{
  "enable": true,
  "maxSize": 10240,
  "validateDomain": true,
  "rateLimit": {"count": 5, "period": "1h"},
  "deliverTo": ["jane@example.org", "john@example.org"],
  "fieldEmail": "email",
  "defaultFromAddress": "unknown@sender.org",
  "fieldHoneyPot": "subject",
  "fieldName": "name",
  "defaultName": "Anonymous",
  "fieldSubject": "subject",
  "defaultSubject": "Contact Form"
}
```

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

### Check if String Starts With Prefix

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

Returns true if the first string starts with the second. Useful for identifying strings with specific beginnings.

```text
starts_with(authenticated_as, 'svc-')
```

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

### Running Proxy Binary with Configuration File

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

Execute the proxy binary, providing the path to its TOML configuration file as a command-line argument. Alternatively, the path can be specified using the PROXY_CONFIG environment variable.

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

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

### Create a WebHook using CLI

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

Use `stalwart-cli` to create a new webhook. Configure URL, authentication, and event settings using `--field` flags.

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