StoreLookup

Defines an external store used for lookups.

This object can be configured from the WebUI under Settings › Lookups › Store Lookups

Fields

`namespace`

Type: String · read-only

Unique identifier for this store when used in lookups

`store`

Type: LookupStore · required

Store to use for lookups

JMAP API

The StoreLookup object is available via the urn:stalwart:jmap capability.

`x:StoreLookup/get`

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

This method requires the sysStoreLookupGet permission.

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

`x:StoreLookup/set`

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

Supports the following operations in a single call: create, update, destroy.

Create

This operation requires the sysStoreLookupCreate permission.

curl -X POST https://mail.example.com/jmap/ \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:StoreLookup/set",
          {
            "create": {
              "new1": {
                "store": {
                  "@type": "PostgreSql",
                  "authSecret": {
                    "@type": "None"
                  },
                  "host": "Example",
                  "readReplicas": {}
                }
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

Update

This operation requires the sysStoreLookupUpdate permission.

curl -X POST https://mail.example.com/jmap/ \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:StoreLookup/set",
          {
            "update": {
              "id1": {
                "store": {
                  "@type": "PostgreSql",
                  "authSecret": {
                    "@type": "None"
                  },
                  "host": "Example",
                  "readReplicas": {}
                }
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

Destroy

This operation requires the sysStoreLookupDestroy permission.

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

`x:StoreLookup/query`

This is a standard Foo/query method as defined in RFC 8620, Section 5.5.

This method requires the sysStoreLookupQuery permission.

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

CLI

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

Fetch

stalwart-cli get StoreLookup id1

Create

stalwart-cli create StoreLookup \
  --field 'store={"@type":"PostgreSql","authSecret":{"@type":"None"},"host":"Example","readReplicas":{}}'

Query

stalwart-cli query StoreLookup

Update

stalwart-cli update StoreLookup id1 --field store='{"@type":"PostgreSql","authSecret":{"@type":"None"},"host":"Example","readReplicas":{}}'

Delete

stalwart-cli delete StoreLookup --ids id1

Nested types

LookupStore

Lookup store backends.

PostgreSql: PostgreSQL. Carries the fields of PostgreSqlStore.
MySql: mySQL. Carries the fields of MySqlStore.
Sqlite: SQLite. Carries the fields of SqliteStore.
Sharded: Sharded Lookup Store. Carries the fields of ShardedInMemoryStore.
Redis: Redis/Valkey. Carries the fields of RedisStore.
RedisCluster: Redis Cluster. Carries the fields of RedisClusterStore.
RedisSentinel: Redis Sentinel. Carries the fields of RedisSentinelStore.
Keep: Stalwart Keep. Carries the fields of KeepStore.

PostgreSqlStore

PostgreSQL data store.

`connectTimeout`

Type: Duration? · default: 15000

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

`responseTimeout`

Type: Duration? · default: 120000

Maximum time to wait for the database server to start answering a request before the connection is closed and the request fails. When unset, requests wait indefinitely.

`useTls`

Type: Boolean · default: false

Use TLS to connect to the store

`allowInvalidCerts`

Type: Boolean · default: false

Allow invalid TLS certificates when connecting to the store

`poolMaxConnections`

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

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

`poolRecyclingMethod`

Type: PostgreSqlRecyclingMethod · default: "fast"

Method to use when recycling connections in the pool

`readReplicas`

Type: List<PostgreSqlSettings> · enterprise

List of read replicas for the store

`host`

Type: String · required

Hostname of the database server

`port`

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

Port of the database server

`database`

Type: String · default: "stalwart"

Name of the database

`authUsername`

Type: String? · default: "stalwart"

Username to connect to the store

`authSecret`

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

Password to connect to the store

`options`

Type: String?

Additional connection options

PostgreSqlSettings

PostgreSQL connection settings.

`host`

Type: String · required

Hostname of the database server

`port`

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

Port of the database server

`database`

Type: String · default: "stalwart"

Name of the database

`authUsername`

Type: String? · default: "stalwart"

Username to connect to the store

`authSecret`

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

Password to connect to the store

`options`

Type: String?

Additional connection options

SecretKeyOptional

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.

SecretKeyValue

A secret value provided directly.

`secret`

Type: String · required · secret

Password or secret value

SecretKeyEnvironmentVariable

A secret value read from an environment variable.

`variableName`

Type: String · required

Environment variable name to read the secret from

SecretKeyFile

A secret value read from a file.

`filePath`

Type: String · required

File path to read the secret from

MySqlStore

MySQL data store.

`idleTimeout`

Type: Duration? · default: 15000

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

`useTls`

Type: Boolean · default: false

Use TLS to connect to the store

`allowInvalidCerts`

Type: Boolean · default: false

Allow invalid TLS certificates when connecting to the store

`maxAllowedPacket`

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

Maximum size of a packet in bytes

`poolMaxConnections`

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

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

`poolMinConnections`

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

Minimum number of connections to the store

`readReplicas`

Type: List<MySqlSettings> · enterprise

List of read replicas for the store

`host`

Type: String · required

Hostname of the database server

`port`

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

Port of the database server

`database`

Type: String · default: "stalwart"

Name of the database

`authUsername`

Type: String? · default: "stalwart"

Username to connect to the store

`authSecret`

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

Password to connect to the store

MySqlSettings

MySQL connection settings.

`host`

Type: String · required

Hostname of the database server

`port`

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

Port of the database server

`database`

Type: String · default: "stalwart"

Name of the database

`authUsername`

Type: String? · default: "stalwart"

Username to connect to the store

`authSecret`

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

Password to connect to the store

SqliteStore

SQLite embedded data store.

`path`

Type: String · required

Path to the SQLite database file, created if missing. When a directory is given, the database is stored in it as stalwart.db

`poolWorkers`

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

Number of worker threads to use for the store, defaults to the number of cores

`poolMaxConnections`

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

Maximum number of connections to the store. When unset, the number of worker threads, between 4 and 16.

ShardedInMemoryStore

Sharded in-memory store configuration.

`stores`

Type: List<InMemoryStoreBase> · min items: 2

Stores to use for sharding

InMemoryStoreBase

In-memory store backends.

Redis: Redis/Valkey. Carries the fields of RedisStore.
RedisCluster: Redis Cluster. Carries the fields of RedisClusterStore.
RedisSentinel: Redis Sentinel. Carries the fields of RedisSentinelStore.

RedisStore

Redis/Valkey store.

`url`

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

URL of the Redis server

`connectTimeout`

Type: Duration · default: 10000

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

`allowInvalidCerts`

Type: Boolean · default: false

Allow invalid TLS certificates when connecting to the Redis server

`poolMaxConnections`

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

Maximum number of connections to the store

`poolTimeoutCreate`

Type: Duration? · default: 30000

Timeout for creating a new connection

`poolTimeoutWait`

Type: Duration? · default: 30000

Timeout for waiting for a connection from the pool

`poolTimeoutRecycle`

Type: Duration? · default: 30000

Timeout for recycling a connection

RedisClusterStore

Redis Cluster store.

`urls`

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

URL(s) of the Redis server(s)

`connectTimeout`

Type: Duration · default: 10000

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

`allowInvalidCerts`

Type: Boolean · default: false

Allow invalid TLS certificates when connecting to the Redis server

`authUsername`

Type: String?

Username to connect to the store

`authSecret`

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

Password to connect to the store

`maxRetryWait`

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

Maximum time to wait between retries

`minRetryWait`

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

Minimum time to wait between retries

`maxRetries`

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

Number of retries to connect to the Redis cluster

`readFromReplicas`

Type: Boolean · default: true

Whether to read from replicas

`protocolVersion`

Type: RedisProtocol · default: "resp2"

Protocol Version

`poolMaxConnections`

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

Maximum number of connections to the store

`poolTimeoutCreate`

Type: Duration? · default: 30000

Timeout for creating a new connection

`poolTimeoutWait`

Type: Duration? · default: 30000

Timeout for waiting for a connection from the pool

`poolTimeoutRecycle`

Type: Duration? · default: 30000

Timeout for recycling a connection

RedisSentinelStore

Redis Sentinel store.

`urls`

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

Address(es) of the Sentinel node(s)

`serviceName`

Type: String · default: "mymaster"

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

`connectTimeout`

Type: Duration · default: 10000

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

`allowInvalidCerts`

Type: Boolean · default: false

Allow invalid TLS certificates when connecting to the Redis server

`authUsername`

Type: String?

Username to connect to the data nodes

`authSecret`

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

Password to connect to the data nodes

`sentinelUsername`

Type: String?

Username to connect to the Sentinel nodes

`sentinelSecret`

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

Password to connect to the Sentinel nodes

`protocolVersion`

Type: RedisProtocol · default: "resp2"

Protocol Version

`poolMaxConnections`

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

Maximum number of connections to the store

`poolTimeoutCreate`

Type: Duration? · default: 30000

Timeout for creating a new connection

`poolTimeoutWait`

Type: Duration? · default: 30000

Timeout for waiting for a connection from the pool

`poolTimeoutRecycle`

Type: Duration? · default: 30000

Timeout for recycling a connection

KeepStore

Stalwart Keep store.

`hosts`

Type: Set<String> · default: {"127.0.0.1:7000":true} · min items: 1

Stalwart Keep servers to connect to, as host:port pairs. With cluster discovery these are the seeds from which the members are learned; without it only the first one is used

`clusterDiscovery`

Type: Boolean · default: false

Learn the members of a Stalwart Keep cluster from the servers listed and place each key on the member that owns it. Requires the cluster secret

`secret`

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

Cluster secret, as 32 hexadecimal digits. Required for cluster discovery and for connections without TLS. When set, each request is sent directly to the shard that owns its key

`tls`

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

How connections to Stalwart Keep are protected and authenticated

`connections`

Type: UnsignedInt · default: 16 · min: 1 · max: 1024

Number of connections per server when no cluster secret is set

`shardConnections`

Type: UnsignedInt · default: 2 · min: 1 · max: 8

Number of connections per server shard when the cluster secret is set

`streamMode`

Type: KeepStreamMode · default: "everywhere"

Which servers carry cluster events when this store is the cluster coordinator

`connectTimeout`

Type: Duration · default: 5000

Maximum time to wait for the servers when the store is opened, and for a connection to be established

`attemptTimeout`

Type: Duration · default: 1000

Maximum time to wait for the reply to one attempt of a request

`deadline`

Type: Duration · default: 5000

Maximum time a request may take over all its attempts. Must not be shorter than the attempt timeout

KeepTls

How connections to Stalwart Keep are protected and authenticated.

Disabled: Plaintext, authenticated with the cluster secret. No additional fields.
RawPublicKeys: Mutual TLS with raw public keys. Carries the fields of KeepTlsRawPublicKeys.
Authority: Mutual TLS with certificates from a cluster CA. Carries the fields of KeepTlsAuthority.

KeepTlsRawPublicKeys

Mutual TLS 1.3 with raw public keys. Files are read from each node’s filesystem when the store is opened, so every node can have its own key at the same path.

`keyPath`

Type: String · required

Path of this node’s private key file, in PEM or DER format

`serverKeysPath`

Type: String · required

Path of the PEM file listing the public keys of the Stalwart Keep servers to accept

KeepTlsAuthority

Mutual TLS 1.3 with certificates from a cluster CA. Files are read from each node’s filesystem when the store is opened, so every node can have its own certificate at the same path.

`caPath`

Type: String · required

Path of the cluster CA certificate file

`certPath`

Type: String · required

Path of this node’s certificate chain file

`keyPath`

Type: String · required

Path of this node’s private key file

`serverName`

Type: String?

Name the server certificates must carry. Leave empty to use the host of each server

Enums

PostgreSqlRecyclingMethod

Value	Label
`fast`	Fast recycling method
`verified`	Verified recycling method
`clean`	Clean recycling method

RedisProtocol

Value	Label
`resp2`	RESP2
`resp3`	RESP3

KeepStreamMode

Value	Label
`everywhere`	Subscribe on every server and publish on one
`owner`	Subscribe and publish on one server chosen per cluster