DOCSEARCHbyAlgolia
Submit Docs

Stalwart Mail & Collaboration Server

repository·main·Indexed 12 days ago

https://github.com/stalwartlabs/stalwart

A high-performance, open-source mail and collaboration server written in Rust. It provides comprehensive support for modern protocols including JMAP, IMAP, SMTP, CalDAV, CardDAV, and WebDAV. Features include LLM-driven spam protection, S/MIME and OpenPGP encryption, and support for multiple storage backends such as PostgreSQL, MySQL, and S3-compatible storage. Designed for scalability from small setups to large-scale, fault-tolerant deployments using cluster coordination tools like Kafka, Redpanda, NATS, or Redis.

Tokens
37.8K
Snippets
73
Records
162
Agent score
96%

What's inside Stalwart

  1. Overview of Stalwart Mail & Collaboration Server

    main

    Stalwart is an open-source, secure, and scalable mail and collaboration server written in Rust. It provides comprehensive protocol support for email, calendaring, contact management, and file storage. It is designed for high availability and can scale from small individual setups to large-scale deployments using cluster coordination tools like Kafka, Redpanda, NATS, or Redis.

    Core Capabilities

    Email Protocols

    • JMAP: Full support for Mail, Sieve Scripts, WebSocket, Blob Management, and Quotas.
    • IMAP: Supports IMAP4rev1, IMAP4rev2, and ManageSieve.
    • POP3: Supports STLS and SASL extensions.
    • SMTP: Includes built-in DMARC, DKIM (v1 and v2), SPF, and ARC. Supports DANE, MTA-STS, and SMTP TLS reporting, with automated DKIM key rotation.

    Collaboration & Storage

    • Calendaring: CalDAV, CalDAV Scheduling, and JMAP for Calendars.
    • Contacts: CardDAV and JMAP for Contacts.
    • File Storage: WebDAV and JMAP for File Storage.
    • Sharing: WebDAV ACL and JMAP Sharing with fine-grained access controls.

    Security & Spam Protection

    • Spam/Phishing: LLM-driven analysis, statistical classifiers, DNSBL checking, Pyzor integration, greylisting, and sender reputation monitoring.
    • Encryption: S/MIME and OpenPGP for encryption at rest.
    • TLS: Automatic certificate provisioning via ACME (supporting DNS-01, HTTP-01, etc.).
    • Authentication: Supports OIDC, OAuth 2.0, LDAP, SQL, and 2FA-TOTP.

    Extensibility & Observability

    • Storage Backends: RocksDB, FoundationDB, PostgreSQL, MySQL, SQLite, S3-Compatible, Azure, and Redis.
    • Search: Built-in engine (17 languages) or external backends like Meilisearch, ElasticSearch, OpenSearch, PostgreSQL, or MySQL.
    • Observability: OpenTelemetry, Prometheus, and Webhooks for events and alerts.

  2. Understand the Stalwart Roadmap and Feature Status

    main
    Stalwart is currently considered feature complete, meaning all core functionality and open standard email and collaboration protocols are implemented. The current development focus is on refinement, specifically finalizing the database schema and implementing performance optimizations in preparation for version 1.0. Users can influence the development priority of new enhancements by voting (giving a thumbs up) on proposals in the GitHub issues tracker.

  3. Account name requirements in v0.16

    main

    In v0.16, all user and group principals must use a full email address (e.g., alice@example.com) instead of a bare username (e.g., alice).

    Impact on Clients

    • Email Clients: Stalwart automatically appends the default domain when a client authenticates with a bare username, so existing mail clients should continue to work.
    • External Directories (LDAP/SQL): You must update your directory filters to query by full email address. Old filters using bare usernames will no longer match.
    • CalDAV, CardDAV, and WebWebDAV: These clients use the account name in the URL path. Because the account name is now an email address, the @ character must be URL-encoded as %40.

    Example URL change:

    • Old: /dav/cal/alice
    • New: /dav/cal/alice%40example.com

    Users must manually reconfigure these clients to point to the new encoded path.

  4. Understand changes to accounts and permissions in v0.10.0

    main

    In version 0.10.0, Stalwart transitioned from a model of 'administrator/super user' accounts to a role-based access control (RBAC) system.

    • Account Type: There is now a single account type called the individual principal.
    • Access Control: Administrator access is granted by assigning the admin role or specific custom permissions to an individual principal.
    • Database Migration: The database layout has changed to support these roles. While the migration is automatic, it is highly recommended to perform a full data backup before upgrading.

  5. Understand Stalwart Licensing and Enterprise Options

    main

    Stalwart is dual-licensed under two different models:

    1. GNU Affero General Public License v3.0 (AGPL-3.0): A free software license that allows use, modification, and distribution, provided that modified versions are also distributed under the same license.
    2. Stalwart Enterprise License v2 (SELv2): A proprietary license designed for commercial use, offering additional features and flexibility for businesses that prefer not to comply with AGPL-3.0 requirements.

    Each file in the repository contains a license notice at the top following REUSE guidelines. Full license texts are located in the LICENSES/ directory.

  6. How configuration works in v0.16

    main

    In v0.16, Stalwart has moved away from TOML configuration files for server settings.

    The New Model

    • config.json: A single, small file on disk that describes only the datastore (the database used by Stalwart).
    • JMAP Objects: All other settings (domains, accounts, mail routing, DKIM, storage backends, spam rules, etc.) are now stored inside the datastore as JMAP objects.

    Infrastructure-as-Code (IaC) Workflow

    For users of Ansible, NixOS, or Terraform, the config.json remains a plain file. However, instead of editing TOML files, you manage server state via the stalwart-cli apply command. This command accepts a declarative plan file and idempotently reconciles the live server state to match it.

    Workflow:

    1. Commit a declarative plan to version control.
    2. Deploy config.json using your existing tooling.
    3. Invoke stalwart-cli apply as an idempotent step in your deployment script.

  7. JMAP replaces REST API for management

    main

    The /api/... REST endpoints from previous releases have been removed. All management operations in v0.16 are now performed through JMAP objects reachable at the /jmap endpoint.

    JMAP (RFC 8620) is used for both email metadata and server administration. This provides:

    • Batch operations: Applying dozens of changes in a single round-trip.
    • Consistency: The same authentication flow and protocol cover both mail access and administration.
    • Tooling: The new stalwart-cli is the primary tool for interacting with this management surface.

  8. Run Stalwart in Recovery Mode

    main

    Recovery mode is a one-shot migration path used during upgrades. When STALWART_RECOVERY_MODE=1 is set, the server:

    • Wipes incompatible subspaces.
    • Migrates the spam classifier model.
    • Opens only the management HTTP endpoint on port 8080 (mail ports remain closed).

    To provision a temporary admin for the CLI to use during migration, set the STALWART_RECOVERY_ADMIN environment variable in the format username:password. This account is temporary and should be replaced by a real administrator via the WebUI after the migration.

    sudo -u stalwart env \
    STALWART_RECOVERY_MODE=1 \
    STALWART_RECOVERY_ADMIN=admin:someTemporaryPassword \
    /usr/local/bin/stalwart --config=/etc/stalwart/config.json

  10. Migrating from v0.12.x (or v0.11.x) to v0.13.x

    main

    Version 0.13.x introduces a major redesign of the MTA's delivery and queueing subsystem.

    Key Changes

    • Message Queue Serialization: A new format is used. Upon the first launch of 0.13.0, any messages in the outbound queue are automatically migrated internally. No manual intervention is required for the queue itself.
    • Strategy-based Configuration: Routing, scheduling, and delivery control have moved to a strategy-based model.

    Configuration Warning

    Important: The previous configuration format for routing is not compatible with v0.13.x.

    • If you use default settings, no changes are required.
    • If you use custom routing rules or queueing logic, you must manually reconfigure them using the new strategy framework.

  11. Upgrade from v0.15.x to v0.16.x

    main

    Upgrading to Stalwart v0.16.x involves significant breaking changes to the configuration and management layer. While user data (emails, calendars, contacts, files, blobs, search indexes) remains unchanged on disk, the way the server is configured is completely incompatible with previous versions.

    Critical Warnings

    • Incompatibility: The configuration model is entirely different. Skipping migration steps can leave the server in an unrecoverable state.
    • Downtime: A manual migration requires a scheduled maintenance window.
    • Zero-Downtime Option: If you cannot afford downtime, wait for the upcoming release of the zero-downtime migration utility and the proxy tool, which allow account-by-account migration while both servers are running.

    Migration Strategy

    It is strongly recommended to:

    1. Install a fresh v0.16 instance (e.g., in Docker) to familiarize yourself with the new WebUI and CLI.
    2. Configure your settings in the test instance.
    3. Use the stalwart-cli snapshot command to export these settings as a JSON file. This file can be used as an apply plan for your production instance after migration.

  12. Upgrade from v0.9.x to v0.10.0

    main

    To upgrade from version 0.9.x to 0.10.0, follow this specific sequence to ensure you do not lose access to the management interface.

    Crucial Order of Operations:

    1. Upgrade the Webadmin FIRST. This ensures you maintain access to the management interface after the mail server is upgraded.
    2. Backup your data.
    3. Upgrade the Mail Server.

    1. Upgrade Webadmin

    In the webadmin interface, navigate to Manage > Maintenance > Update Webadmin and follow the prompts.