Skip to content

Cache

Configures in-memory cache sizes for data, DNS records, and authorization tokens.

This object can be configured from the WebUI under Settings › Storage › Cache

Type: Size · default: 10485760 · min: 2048

Maximum size of the access tokens cache

Type: Size · default: 33554432 · min: 2048

Maximum size of the address books and contacts cache

Type: Size · default: 2097152 · min: 2048

Maximum size of the IPv4 record cache

Type: Size · default: 1048576 · min: 2048

Maximum size of the IPv6 record cache

Type: Size · default: 1048576 · min: 2048

Maximum size of the MTA-STS record cache

Type: Size · default: 2097152 · min: 2048

Maximum size of the MX record cache

Type: Size · default: 1048576 · min: 2048

Maximum size of the PTR record cache

Type: Size · default: 6291456 · min: 2048

Maximum size of the spam filter lookup cache, which holds DNSBL results and resolved URL redirects

Type: Size · default: 1048576 · min: 2048

Maximum size of the TLSA record cache

Type: Size · default: 8388608 · min: 2048

Maximum size of the TXT record cache

Type: Size · default: 50331648 · min: 2048

Maximum size of the calendar and events cache

Type: Size · default: 6291456 · min: 2048

Maximum size of the scheduling cache

Type: Size · default: 25165824 · min: 2048

Maximum size of the file storage data cache

Type: Size · default: 2097152 · min: 2048

Maximum size of the HTTP authorization headers cache

Type: Size · default: 335544320 · min: 2048

Maximum size of the e-mail data cache

Type: Size · default: 536870912

Maximum size of the e-mail data cache for accounts too large for the main e-mail data cache. Set it to zero to disable it, so that these accounts are only shared between the requests using them at the same time

Type: Duration · default: 3600000

Minimum time the e-mail data cache of a large account is kept in memory after it was last used. Once it has passed, the cache is released the next time an e-mail data cache is updated. Set it to zero to keep these caches until the space is needed for another large account

Type: Size · default: 536870912

Maximum size of the calendar, contact, file and scheduling caches for accounts too large for their main cache. Set it to zero to disable it, so that these accounts are only shared between the requests using them at the same time

Type: Duration · default: 3600000

Minimum time the calendar, contact, file or scheduling cache of a large account is kept in memory after it was last used. Once it has passed, the cache is released the next time one of these caches is updated. Set it to zero to keep these caches until the space is needed for another large account

Type: Size · default: 2097152 · min: 2048

Maximum size of the domains cache

Type: Size · default: 1048576 · min: 2048

Maximum size of the domain name lookup cache

Type: Size · default: 2097152 · min: 2048

Maximum size of the domain name lookup negative cache

Type: Size · default: 8388608 · min: 2048

Maximum size of the email addresses lookup cache

Type: Size · default: 2097152 · min: 2048

Maximum size of the email addresses lookup negative cache

Type: Size · default: 16777216 · min: 2048

Maximum size of the accounts cache

Type: Size · default: 1048576 · min: 2048

Maximum size of the roles cache

Type: Size · enterprise · default: 1048576 · min: 2048

Maximum size of the tenants cache

Type: Size · default: 2097152 · min: 2048

Maximum size of the mailing lists cache

Type: Size · default: 8388608 · min: 2048

Maximum size of the DKIM signatures cache

Type: Duration · default: 3600000

Time-to-live for negative cache entries of domain and account name lookups, and the maximum time a negative DNS answer is cached

Type: Size · default: 2097152 · min: 2048

Maximum size of the cache that records which recipients were recently resolved against an external directory

Type: Duration · default: 600000

How long a recipient resolved against an external directory is trusted before the directory is queried again

Type: CacheSwap · default: {"@type":"Disabled"}

Where account cache snapshots are persisted, so a cache miss reloads a snapshot and catches it up from the change log instead of rebuilding the whole cache from the data store

The Cache singleton is available via the urn:stalwart:jmap capability.

This is a standard Foo/get method as defined in RFC 8620, Section 5.1.

For singletons, the ids argument should be the literal singleton (or null to return the single instance).

This method requires the sysCacheGet permission.

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

This is a standard Foo/set method as defined in RFC 8620, Section 5.3.

For singletons, only the update argument with id singleton is accepted; create and destroy arguments are rejected.

This method requires the sysCacheUpdate permission.

Terminal window
curl -X POST https://mail.example.com/jmap/ \
-H 'Authorization: Bearer $TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"methodCalls": [
[
"x:Cache/set",
{
"update": {
"singleton": {
"accessTokens": 10485760
}
}
},
"c1"
]
],
"using": [
"urn:ietf:params:jmap:core",
"urn:stalwart:jmap"
]
}'

stalwart-cli wraps the same JMAP calls. See the CLI reference for installation, authentication, and general usage.

Terminal window
stalwart-cli get Cache
Terminal window
stalwart-cli update Cache --field accessTokens=10485760

Where account cache snapshots are persisted.

  • Disabled: Disabled. No additional fields.
  • LocalFile: Node-local file. Carries the fields of LocalFileSwap.
  • Redis: In-memory store (Redis only). Carries the fields of RedisSwap.
  • BlobStore: Blob store. Carries the fields of BlobStoreSwap.

Cache snapshots stored on this node’s filesystem.

Type: String · required

Directory in which cache snapshots are stored

Type: UnsignedInt · default: 2000 · min: 1

Minimum number of changes accumulated against an account cache before its snapshot is rewritten. Large accounts need proportionally more: one sixteenth of the messages or resources in the cache

Type: Duration · default: 600000

Shortest interval between two snapshot writes for the same account

Type: Size · default: 1073741824 · min: 2048

Largest snapshot that will be persisted. Accounts whose snapshot would exceed this are skipped

Type: Size · default: 1048576

Smallest snapshot worth persisting. Below this the rebuild costs less than the write, so the account is skipped. This is the uncompressed snapshot size, which is close to the account’s in-memory cache size and much smaller than its compressed size in the database

Cache snapshots stored in Redis, shared across all nodes in the cluster.

Type: RedisSwapStore · default: {"@type":"Default"}

Redis deployment in which cache snapshots are stored

Type: Size · default: 1048576 · min: 65536

Size of each snapshot chunk written to Redis

Type: Duration · default: 604800000

How long a snapshot survives in Redis without being rewritten before it expires

Type: UnsignedInt · default: 2000 · min: 1

Minimum number of changes accumulated against an account cache before its snapshot is rewritten. Large accounts need proportionally more: one sixteenth of the messages or resources in the cache

Type: Duration · default: 600000

Shortest interval between two snapshot writes for the same account

Type: Size · default: 1073741824 · min: 2048

Largest snapshot that will be persisted. Accounts whose snapshot would exceed this are skipped

Type: Size · default: 1048576

Smallest snapshot worth persisting. Below this the rebuild costs less than the write, so the account is skipped. This is the uncompressed snapshot size, which is close to the account’s in-memory cache size and much smaller than its compressed size in the database

Redis deployment used to store cache snapshots.

  • Default: Use in-memory store (Redis only). No additional fields.
  • Redis: Redis/Valkey. Carries the fields of RedisStore.
  • RedisCluster: Redis Cluster. Carries the fields of RedisClusterStore.
  • RedisSentinel: Redis Sentinel. Carries the fields of RedisSentinelStore.

Redis/Valkey store.

Type: Uri · default: "redis://127.0.0.1"

URL of the Redis server

Type: Duration · default: 10000

Maximum time to wait for a new connection to the Redis server to be established

Type: Boolean · default: false

Allow invalid TLS certificates when connecting to the Redis server

Type: UnsignedInt · default: 10 · max: 8192 · min: 1

Maximum number of connections to the store

Type: Duration? · default: 30000

Timeout for creating a new connection

Type: Duration? · default: 30000

Timeout for waiting for a connection from the pool

Type: Duration? · default: 30000

Timeout for recycling a connection

Redis Cluster store.

Type: Set<Uri> · default: {"redis://127.0.0.1":true}

URL(s) of the Redis server(s)

Type: Duration · default: 10000

Maximum time to wait for a new connection to the Redis server to be established

Type: Boolean · default: false

Allow invalid TLS certificates when connecting to the Redis server

Type: String?

Username to connect to the store

Type: SecretKeyOptional · default: {"@type":"None"}

Password to connect to the store

Type: Duration? · max: 1024 · min: 1

Maximum time to wait between retries

Type: Duration? · max: 1024 · min: 1

Minimum time to wait between retries

Type: UnsignedInt? · max: 1024 · min: 1

Number of retries to connect to the Redis cluster

Type: Boolean · default: true

Whether to read from replicas

Type: RedisProtocol · default: "resp2"

Protocol Version

Type: UnsignedInt · default: 10 · max: 8192 · min: 1

Maximum number of connections to the store

Type: Duration? · default: 30000

Timeout for creating a new connection

Type: Duration? · default: 30000

Timeout for waiting for a connection from the pool

Type: Duration? · default: 30000

Timeout for recycling a connection

An optional secret value, or none.

  • None: No secret. No additional fields.
  • Value: Secret value. Carries the fields of SecretKeyValue.
  • EnvironmentVariable: Secret read from environment variable. Carries the fields of SecretKeyEnvironmentVariable.
  • File: Secret read from file. Carries the fields of SecretKeyFile.

A secret value provided directly.

Type: String · required · secret

Password or secret value

A secret value read from an environment variable.

Type: String · required

Environment variable name to read the secret from

A secret value read from a file.

Type: String · required

File path to read the secret from

Redis Sentinel store.

Type: Set<Uri> · default: {"redis://127.0.0.1:26379":true}

Address(es) of the Sentinel node(s)

Type: String · default: "mymaster"

Name of the monitored master (service) to query via the Sentinels

Type: Duration · default: 10000

Maximum time to wait for a new connection to the Redis server to be established

Type: Boolean · default: false

Allow invalid TLS certificates when connecting to the Redis server

Type: String?

Username to connect to the data nodes

Type: SecretKeyOptional · default: {"@type":"None"}

Password to connect to the data nodes

Type: String?

Username to connect to the Sentinel nodes

Type: SecretKeyOptional · default: {"@type":"None"}

Password to connect to the Sentinel nodes

Type: RedisProtocol · default: "resp2"

Protocol Version

Type: UnsignedInt · default: 10 · max: 8192 · min: 1

Maximum number of connections to the store

Type: Duration? · default: 30000

Timeout for creating a new connection

Type: Duration? · default: 30000

Timeout for waiting for a connection from the pool

Type: Duration? · default: 30000

Timeout for recycling a connection

Cache snapshots stored in a blob store, shared across all nodes in the cluster.

Type: BlobSwapStore · default: {"@type":"Default"}

Blob store in which cache snapshots are stored

Type: Duration · default: 604800000

How long a snapshot survives in the blob store without being rewritten before the cleanup task removes it

Type: UnsignedInt · default: 2000 · min: 1

Minimum number of changes accumulated against an account cache before its snapshot is rewritten. Large accounts need proportionally more: one sixteenth of the messages or resources in the cache

Type: Duration · default: 600000

Shortest interval between two snapshot writes for the same account

Type: Size · default: 1073741824 · min: 2048

Largest snapshot that will be persisted. Accounts whose snapshot would exceed this are skipped

Type: Size · default: 1048576

Smallest snapshot worth persisting. Below this the rebuild costs less than the write, so the account is skipped. This is the uncompressed snapshot size, which is close to the account’s in-memory cache size and much smaller than its compressed size in the database

Blob store used to store cache snapshots.

  • Default: Use blob store. No additional fields.
  • S3: S3-compatible. Carries the fields of S3Store.
  • Azure: Azure blob storage. Carries the fields of AzureStore.
  • FileSystem: Filesystem. Carries the fields of FileSystemStore.
  • FoundationDb: FoundationDB. Carries the fields of FoundationDbStore.
  • PostgreSql: PostgreSQL. Carries the fields of PostgreSqlStore.
  • MySql: mySQL. Carries the fields of MySqlStore.

S3-compatible blob store.

Type: S3StoreRegion · default: {"@type":"UsEast1"}

The S3 region where the bucket resides

Type: String · required

The S3 bucket where blobs (e-mail messages, Sieve scripts, etc.) will be stored

Type: PublicStringOptional · default: {"@type":"None"}

Access key ID that identifies the S3 account

Type: SecretKeyOptional · default: {"@type":"None"}

The secret access key for the S3 account

Type: SecretKeyOptional · default: {"@type":"None"}

Session token for temporary credentials, sent as the x-amz-security-token header

Type: String?

Used when retrieving credentials from a shared credentials file. If specified, the server will use the access key ID, secret access key, and session token (if available) associated with the given profile

Type: Duration · default: 30000

Request timeout for S3 operations

Type: UnsignedInt · default: 3 · max: 10

The maximum number of times to retry failed requests. Set to 0 to disable retries

Type: String?

A prefix that will be added to the keys of all objects stored in the blob store

Type: Boolean · default: false

Allow invalid TLS certificates when connecting to the S3 service

Type: Boolean · default: true

After each successful write, verify the object is readable on the backend. Defends against the rare case where an S3-compatible backend returns success but does not actually persist the data. Adds one extra request per write.

Predefined S3 regions.

  • UsEast1: us-east-1. No additional fields.
  • UsEast2: us-east-2. No additional fields.
  • UsWest1: us-west-1. No additional fields.
  • UsWest2: us-west-2. No additional fields.
  • CaCentral1: ca-central-1. No additional fields.
  • AfSouth1: af-south-1. No additional fields.
  • ApEast1: ap-east-1. No additional fields.
  • ApSouth1: ap-south-1. No additional fields.
  • ApNortheast1: ap-northeast-1. No additional fields.
  • ApNortheast2: ap-northeast-2. No additional fields.
  • ApNortheast3: ap-northeast-3. No additional fields.
  • ApSoutheast1: ap-southeast-1. No additional fields.
  • ApSoutheast2: ap-southeast-2. No additional fields.
  • CnNorth1: cn-north-1. No additional fields.
  • CnNorthwest1: cn-northwest-1. No additional fields.
  • EuNorth1: eu-north-1. No additional fields.
  • EuCentral1: eu-central-1. No additional fields.
  • EuCentral2: eu-central-2. No additional fields.
  • EuWest1: eu-west-1. No additional fields.
  • EuWest2: eu-west-2. No additional fields.
  • EuWest3: eu-west-3. No additional fields.
  • IlCentral1: il-central-1. No additional fields.
  • MeSouth1: me-south-1. No additional fields.
  • SaEast1: sa-east-1. No additional fields.
  • DoNyc3: Digital Ocean nyc3. No additional fields.
  • DoAms3: Digital Ocean ams3. No additional fields.
  • DoSgp1: Digital Ocean sgp1. No additional fields.
  • DoFra1: Digital Ocean fra1. No additional fields.
  • Yandex: Yandex Object Storage. No additional fields.
  • WaUsEast1: Wasabi us-east-1. No additional fields.
  • WaUsEast2: Wasabi us-east-2. No additional fields.
  • WaUsCentral1: Wasabi us-central-1. No additional fields.
  • WaUsWest1: Wasabi us-west-1. No additional fields.
  • WaCaCentral1: Wasabi ca-central-1. No additional fields.
  • WaEuCentral1: Wasabi eu-central-1. No additional fields.
  • WaEuCentral2: Wasabi eu-central-2. No additional fields.
  • WaEuWest1: Wasabi eu-west-1. No additional fields.
  • WaEuWest2: Wasabi eu-west-2. No additional fields.
  • WaApNortheast1: Wasabi ap-northeast-1. No additional fields.
  • WaApNortheast2: Wasabi ap-northeast-2. No additional fields.
  • WaApSoutheast1: Wasabi ap-southeast-1. No additional fields.
  • WaApSoutheast2: Wasabi ap-southeast-2. No additional fields.
  • Custom: Custom. Carries the fields of S3StoreCustomRegion.

Custom S3-compatible endpoint.

Type: Uri · required

Endpoint URL

Type: String · required

Region name

An optional public value, or none.

A public value provided directly.

Type: String · required

Value

Azure Blob Storage store.

Type: String · required

The Azure Storage Account where blobs (e-mail messages, Sieve scripts, etc.) will be stored

Type: String · required

The name of the container in the Storage Account

Type: AzureEnvironment · default: "public"

Azure cloud environment, used to derive the default blob service URL and the Microsoft Entra ID authority

Type: Uri?

Custom blob service URL, for private endpoints or the Azurite emulator. When empty, it is derived from the storage account and the cloud environment

Type: AzureAuth · required

Authentication method used to access the Storage Account

Type: Duration · default: 30000

Request timeout for Azure Blob Storage operations

Type: UnsignedInt · default: 3 · max: 10

The maximum number of times to retry failed requests. Set to 0 to disable retries

Type: String?

A prefix that will be added to the keys of all objects stored in the blob store

Azure Blob Storage authentication method.

Azure Storage Account shared key authentication.

Type: SecretKey · required

The shared key of the Azure Storage Account

A secret value provided directly, from an environment variable, or from a file.

Azure shared access signature (SAS) token authentication.

Type: SecretKey · required

SAS token granting read, write and delete permissions on the container. The leading ’?’ is optional

Microsoft Entra ID service principal authentication using a client secret.

Type: String · required

Microsoft Entra ID tenant ID

Type: String · required

Application (client) ID of the service principal

Type: SecretKey · required

Application client secret

Azure managed identity authentication.

Type: String?

Client ID of a user-assigned managed identity. When empty, the system-assigned identity is used

Microsoft Entra Workload ID authentication using a federated token file.

Type: String?

Microsoft Entra ID tenant ID. When empty, the AZURE_TENANT_ID environment variable is used

Type: String?

Application (client) ID. When empty, the AZURE_CLIENT_ID environment variable is used

Type: String?

Path to the federated token file. When empty, the AZURE_FEDERATED_TOKEN_FILE environment variable is used

Filesystem blob store.

Type: String · required

Where to store the data in the server’s filesystem

Type: UnsignedInt · default: 2 · max: 5

Maximum depth of nested directories

FoundationDB data store.

Type: String?

Path to the cluster file for the FoundationDB cluster

Type: String?

Data center ID (optional)

Type: String?

Machine ID in the FoundationDB cluster (optional)

Type: Duration?

Transaction maximum retry delay

Type: UnsignedInt? · max: 1000 · min: 1

Transaction retry limit

Type: Duration?

Transaction timeout

PostgreSQL data store.

Type: Duration? · default: 15000

Maximum time to wait for a connection to the database server to be established

Type: Boolean · default: false

Use TLS to connect to the store

Type: Boolean · default: false

Allow invalid TLS certificates when connecting to the store

Type: UnsignedInt? · max: 8192 · min: 1

Maximum number of connections to the store. When unset, 4 per CPU core, between 16 and 32.

Type: PostgreSqlRecyclingMethod · default: "fast"

Method to use when recycling connections in the pool

Type: List<PostgreSqlSettings> · enterprise

List of read replicas for the store

Type: String · required

Hostname of the database server

Type: UnsignedInt · default: 5432 · max: 65535 · min: 1

Port of the database server

Type: String · default: "stalwart"

Name of the database

Type: String? · default: "stalwart"

Username to connect to the store

Type: SecretKeyOptional · default: {"@type":"None"}

Password to connect to the store

Type: String?

Additional connection options

PostgreSQL connection settings.

Type: String · required

Hostname of the database server

Type: UnsignedInt · default: 5432 · max: 65535 · min: 1

Port of the database server

Type: String · default: "stalwart"

Name of the database

Type: String? · default: "stalwart"

Username to connect to the store

Type: SecretKeyOptional · default: {"@type":"None"}

Password to connect to the store

Type: String?

Additional connection options

MySQL data store.

Type: Duration? · default: 15000

Time an idle connection may stay open before the server closes it (sets the MySQL wait_timeout session variable)

Type: Boolean · default: false

Use TLS to connect to the store

Type: Boolean · default: false

Allow invalid TLS certificates when connecting to the store

Type: UnsignedInt? · max: 1073741824 · min: 1024

Maximum size of a packet in bytes

Type: UnsignedInt? · max: 8192 · min: 1

Maximum number of connections to the store. When unset, 4 per CPU core, between 16 and 32.

Type: UnsignedInt? · default: 5 · max: 8192 · min: 1

Minimum number of connections to the store

Type: List<MySqlSettings> · enterprise

List of read replicas for the store

Type: String · required

Hostname of the database server

Type: UnsignedInt · default: 3306 · max: 65535 · min: 1

Port of the database server

Type: String · default: "stalwart"

Name of the database

Type: String? · default: "stalwart"

Username to connect to the store

Type: SecretKeyOptional · default: {"@type":"None"}

Password to connect to the store

MySQL connection settings.

Type: String · required

Hostname of the database server

Type: UnsignedInt · default: 3306 · max: 65535 · min: 1

Port of the database server

Type: String · default: "stalwart"

Name of the database

Type: String? · default: "stalwart"

Username to connect to the store

Type: SecretKeyOptional · default: {"@type":"None"}

Password to connect to the store

ValueLabel
resp2RESP2
resp3RESP3
ValueLabel
publicPublic
chinaChina
us-governmentUS Government
ValueLabel
fastFast recycling method
verifiedVerified recycling method
cleanClean recycling method