Skip to main content
Version: 0.16

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/api \
  -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 create, update, and destroy operations in a single call.

Create​

This operation requires the sysStoreLookupCreate permission.

curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:StoreLookup/set",
          {
            "create": {
              "new1": {
                "store": {
                  "@type": "PostgreSql",
                  "allowInvalidCerts": false,
                  "authSecret": {
                    "@type": "None"
                  },
                  "authUsername": "stalwart",
                  "database": "stalwart",
                  "host": "mail.example.com",
                  "options": "Example",
                  "poolMaxConnections": 10,
                  "poolRecyclingMethod": "fast",
                  "port": 5432,
                  "readReplicas": [],
                  "timeout": "15s",
                  "useTls": false
                }
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

Update​

This operation requires the sysStoreLookupUpdate permission.

curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:StoreLookup/set",
          {
            "update": {
              "id1": {
                "store": {
                  "@type": "PostgreSql",
                  "allowInvalidCerts": false,
                  "authSecret": {
                    "@type": "None"
                  },
                  "authUsername": "stalwart",
                  "database": "stalwart",
                  "host": "mail.example.com",
                  "options": "Example",
                  "poolMaxConnections": 10,
                  "poolRecyclingMethod": "fast",
                  "port": 5432,
                  "readReplicas": [],
                  "timeout": "15s",
                  "useTls": false
                }
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

Destroy​

This operation requires the sysStoreLookupDestroy permission.

curl -X POST https://mail.example.com/api \
  -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/api \
  -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 store-lookup id1

Create​

stalwart-cli create store-lookup \
  --field 'store={"@type":"PostgreSql","allowInvalidCerts":false,"authSecret":{"@type":"None"},"authUsername":"stalwart","database":"stalwart","host":"mail.example.com","options":"Example","poolMaxConnections":10,"poolRecyclingMethod":"fast","port":5432,"readReplicas":[],"timeout":"15s","useTls":false}'

Query​

stalwart-cli query store-lookup

Update​

stalwart-cli update store-lookup id1 --field description='Updated'

Delete​

stalwart-cli delete store-lookup --ids id1

Nested types​

LookupStore​

Lookup store backends.

PostgreSqlStore​

PostgreSQL data store.

timeout​

Type: Duration? · default: "15s"

Connection timeout to the database

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? · default: 10 · max: 8192 · min: 1

Maximum number of connections to the store

poolRecyclingMethod​

Type: PostgreSqlRecyclingMethod · default: "fast"

Method to use when recycling connections in the pool

readReplicas​

Type: PostgreSqlSettings[] · enterprise

List of read replicas for the store

host​

Type: HostName · 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 · required

Password to connect to the store

options​

Type: String?

Additional connection options

PostgreSqlSettings​

PostgreSQL connection settings.

host​

Type: HostName · 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 · required

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.

timeout​

Type: Duration? · default: "15s"

Connection timeout to the database

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? · default: 10 · max: 8192 · min: 1

Maximum number of connections to the store

poolMinConnections​

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

Minimum number of connections to the store

readReplicas​

Type: MySqlSettings[] · enterprise

List of read replicas for the store

host​

Type: HostName · 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 · required

Password to connect to the store

MySqlSettings​

MySQL connection settings.

host​

Type: HostName · 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 · required

Password to connect to the store

SqliteStore​

SQLite embedded data store.

path​

Type: String · required

Path to the SQLite data directory

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 · default: 10 · max: 8192 · min: 1

Maximum number of connections to the store

ShardedInMemoryStore​

Sharded in-memory store configuration.

stores​

Type: InMemoryStoreBase[] · min items: 2

Stores to use for sharding

InMemoryStoreBase​

In-memory store backends.

RedisStore​

Redis/Valkey store.

url​

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

URL of the Redis server

timeout​

Type: Duration · default: "10s"

Connection timeout to the database

poolMaxConnections​

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

Maximum number of connections to the store

poolTimeoutCreate​

Type: Duration? · default: "30s"

Timeout for creating a new connection

poolTimeoutWait​

Type: Duration? · default: "30s"

Timeout for waiting for a connection from the pool

poolTimeoutRecycle​

Type: Duration? · default: "30s"

Timeout for recycling a connection

RedisClusterStore​

Redis Cluster store.

urls​

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

URL(s) of the Redis server(s)

timeout​

Type: Duration · default: "10s"

Connection timeout to the database

authUsername​

Type: String? · default: "stalwart"

Username to connect to the store

authSecret​

Type: SecretKeyOptional · required

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: "30s"

Timeout for creating a new connection

poolTimeoutWait​

Type: Duration? · default: "30s"

Timeout for waiting for a connection from the pool

poolTimeoutRecycle​

Type: Duration? · default: "30s"

Timeout for recycling a connection

Enums​

PostgreSqlRecyclingMethod​

ValueLabel
fastFast recycling method
verifiedVerified recycling method
cleanClean recycling method

RedisProtocol​

ValueLabel
resp2RESP2
resp3RESP3