Skip to content

S3-compatible

For distributed and larger-scale deployments, Stalwart supports S3-compatible object storage services as a blob store. S3 (Simple Storage Service) is a scalable object-storage protocol supported by many cloud providers. Using an S3-compatible service lets the server hold email bodies, Sieve scripts, and other blobs on remote infrastructure suited to large-scale storage management, replication, and backup.

Configuration

Section titled “Configuration”

The S3-compatible backend is selected by choosing the S3 variant on the BlobStore object (found in the WebUI under Settings › Storage › Blob Store). The variant exposes the following fields:

  • bucket: the S3 bucket where blobs are stored (required).
  • region: the S3 region where the bucket resides (required). A large set of well-known regions is supported; a custom endpoint and region name can be supplied for S3-compatible services such as MinIO.
  • accessKey: the S3 access key identifying the account.
  • secretKey: the secret key associated with the account (required). The secret may be supplied inline, read from an environment variable, or loaded from a file.
  • securityToken and sessionToken: optional tokens used for temporary credentials such as those issued by AWS STS. Leave set to None for permanent IAM credentials or for services that do not support STS.
  • profile: optional profile name for retrieving credentials from a shared credentials file.
  • timeout: maximum time to wait for a response from the S3 service. Default: "30s".
  • maxRetries: maximum number of retries for a failed operation. Default: 3.
  • verifyAfterWrite: when true, performs a HEAD after every successful PUT to confirm the object is readable on the backend. Defends against backends that acknowledge writes without persisting the data. Default: true.
  • keyPrefix: optional prefix prepended to every object key, useful for organising or segregating data within a bucket.
  • allowInvalidCerts: when true, accepts connections with invalid TLS certificates. Default: false.

For a custom S3-compatible endpoint, set region to the Custom variant and supply the target endpoint URL and region name.