AiModel

Defines an AI model endpoint used by AI-assisted features such as the spam classifier and the Sieve llm_prompt function.

This object can be configured from the WebUI under Settings › AI

Fields

AiModel is a multi-variant object: each instance has an @type discriminator selecting one of the variants below, and each variant carries its own set of fields.

`@type: "OpenAi"`

OpenAI compatible

`profile`

Type: AiOpenAiProfile · default: "OpenAi"

Server profile, which selects the token limit parameter, the structured output format and the authentication header

`logprobs`

Type: Boolean · default: false

Whether to request token log probabilities and use them as the classifier confidence

`maxOutputTokens`

Type: UnsignedInt · default: 4096 · min: 1 · max: 1000000

Maximum number of tokens the model may generate, including reasoning tokens. The spam classifier uses its own smaller limit.

`temperature`

Type: Float? · min: 0 · max: 2

Sampling temperature. When empty, the parameter is omitted and the provider default is used.

`reasoning`

Type: AiReasoning · default: "Default"

Reasoning effort requested from the model

`extraParameters`

Type: Text?

JSON object whose members are merged into every request body

`name`

Type: String · required

Short name used to reference this model

`model`

Type: String · required

Model identifier sent to the provider

`url`

Type: Uri?

Base URL of the provider API. When empty, the provider’s default URL is used.

`apiKey`

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

API key sent to the provider using its native authentication header

`httpHeaders`

Type: Map<String, String>

Additional headers to include in requests to the provider

`allowInvalidCerts`

Type: Boolean · default: false

Whether to accept invalid TLS certificates from the endpoint

`timeout`

Type: Duration · default: 60000

Maximum time to wait for a single response from the endpoint

`maxConcurrentRequests`

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

Maximum number of requests sent to this model at the same time

`rateLimit`

Type: Rate?

Maximum number of requests sent to this model within the rate period, spaced evenly. When empty, no rate limit is applied.

`@type: "Anthropic"`

Anthropic

`maxOutputTokens`

Type: UnsignedInt · default: 4096 · min: 1 · max: 1000000

Maximum number of tokens the model may generate, including reasoning tokens. The spam classifier uses its own smaller limit.

`temperature`

Type: Float? · min: 0 · max: 2

Sampling temperature. When empty, the parameter is omitted and the provider default is used.

`reasoning`

Type: AiReasoning · default: "Default"

Reasoning effort requested from the model

`extraParameters`

Type: Text?

JSON object whose members are merged into every request body

`name`

Type: String · required

Short name used to reference this model

`model`

Type: String · required

Model identifier sent to the provider

`url`

Type: Uri?

Base URL of the provider API. When empty, the provider’s default URL is used.

`apiKey`

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

API key sent to the provider using its native authentication header

`httpHeaders`

Type: Map<String, String>

Additional headers to include in requests to the provider

`allowInvalidCerts`

Type: Boolean · default: false

Whether to accept invalid TLS certificates from the endpoint

`timeout`

Type: Duration · default: 60000

Maximum time to wait for a single response from the endpoint

`maxConcurrentRequests`

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

Maximum number of requests sent to this model at the same time

`rateLimit`

Type: Rate?

Maximum number of requests sent to this model within the rate period, spaced evenly. When empty, no rate limit is applied.

`@type: "Gemini"`

Google Gemini

`logprobs`

Type: Boolean · default: false

Whether to request token log probabilities and use them as the classifier confidence

`maxOutputTokens`

Type: UnsignedInt · default: 4096 · min: 1 · max: 1000000

Maximum number of tokens the model may generate, including reasoning tokens. The spam classifier uses its own smaller limit.

`temperature`

Type: Float? · min: 0 · max: 2

Sampling temperature. When empty, the parameter is omitted and the provider default is used.

`reasoning`

Type: AiReasoning · default: "Default"

Reasoning effort requested from the model

`extraParameters`

Type: Text?

JSON object whose members are merged into every request body

`name`

Type: String · required

Short name used to reference this model

`model`

Type: String · required

Model identifier sent to the provider

`url`

Type: Uri?

Base URL of the provider API. When empty, the provider’s default URL is used.

`apiKey`

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

API key sent to the provider using its native authentication header

`httpHeaders`

Type: Map<String, String>

Additional headers to include in requests to the provider

`allowInvalidCerts`

Type: Boolean · default: false

Whether to accept invalid TLS certificates from the endpoint

`timeout`

Type: Duration · default: 60000

Maximum time to wait for a single response from the endpoint

`maxConcurrentRequests`

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

Maximum number of requests sent to this model at the same time

`rateLimit`

Type: Rate?

Maximum number of requests sent to this model within the rate period, spaced evenly. When empty, no rate limit is applied.

`@type: "Ollama"`

Ollama

`logprobs`

Type: Boolean · default: false

Whether to request token log probabilities and use them as the classifier confidence

`keepAlive`

Type: Duration?

How long Ollama keeps the model loaded after a request. When empty, the server default is used.

`maxOutputTokens`

Type: UnsignedInt · default: 4096 · min: 1 · max: 1000000

Maximum number of tokens the model may generate, including reasoning tokens. The spam classifier uses its own smaller limit.

`temperature`

Type: Float? · min: 0 · max: 2

Sampling temperature. When empty, the parameter is omitted and the provider default is used.

`reasoning`

Type: AiReasoning · default: "Default"

Reasoning effort requested from the model

`extraParameters`

Type: Text?

JSON object whose members are merged into every request body

`name`

Type: String · required

Short name used to reference this model

`model`

Type: String · required

Model identifier sent to the provider

`url`

Type: Uri?

Base URL of the provider API. When empty, the provider’s default URL is used.

`apiKey`

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

API key sent to the provider using its native authentication header

`httpHeaders`

Type: Map<String, String>

Additional headers to include in requests to the provider

`allowInvalidCerts`

Type: Boolean · default: false

Whether to accept invalid TLS certificates from the endpoint

`timeout`

Type: Duration · default: 60000

Maximum time to wait for a single response from the endpoint

`maxConcurrentRequests`

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

Maximum number of requests sent to this model at the same time

`rateLimit`

Type: Rate?

Maximum number of requests sent to this model within the rate period, spaced evenly. When empty, no rate limit is applied.

`@type: "TypeSafe"`

TypeSafe

`name`

Type: String · required

Short name used to reference this model

`model`

Type: String · required

Model identifier sent to the provider

`url`

Type: Uri?

Base URL of the provider API. When empty, the provider’s default URL is used.

`apiKey`

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

API key sent to the provider using its native authentication header

`httpHeaders`

Type: Map<String, String>

Additional headers to include in requests to the provider

`allowInvalidCerts`

Type: Boolean · default: false

Whether to accept invalid TLS certificates from the endpoint

`timeout`

Type: Duration · default: 60000

Maximum time to wait for a single response from the endpoint

`maxConcurrentRequests`

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

Maximum number of requests sent to this model at the same time

`rateLimit`

Type: Rate?

Maximum number of requests sent to this model within the rate period, spaced evenly. When empty, no rate limit is applied.

JMAP API

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

`x:AiModel/get`

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

This method requires the sysAiModelGet permission.

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

`x:AiModel/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 sysAiModelCreate permission.

curl -X POST https://mail.example.com/jmap/ \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:AiModel/set",
          {
            "create": {
              "new1": {
                "@type": "OpenAi",
                "apiKey": {
                  "@type": "None"
                },
                "httpHeaders": {},
                "model": "Example",
                "name": "Example"
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

Update

This operation requires the sysAiModelUpdate permission.

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

Destroy

This operation requires the sysAiModelDestroy permission.

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

`x:AiModel/query`

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

This method requires the sysAiModelQuery permission.

curl -X POST https://mail.example.com/jmap/ \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:AiModel/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 AiModel id1

Create

stalwart-cli create AiModel/OpenAi \
  --field name=Example \
  --field model=Example \
  --field 'apiKey={"@type":"None"}' \
  --field 'httpHeaders={}'

Query

stalwart-cli query AiModel

Update

stalwart-cli update AiModel id1 --field extraParameters='updated value'

Delete

stalwart-cli delete AiModel --ids id1

Nested types

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

Rate

Defines a rate limit as a count over a time period.

`count`

Type: UnsignedInt · default: 0 · min: 1 · max: 1000000

Count

`period`

Type: Duration · default: 0 · min: 1

Period

Enums

AiOpenAiProfile

Value	Label
`OpenAi`	OpenAI
`Azure`	Azure OpenAI
`Vllm`	vLLM
`LlamaCpp`	llama.cpp
`Generic`	Generic

AiReasoning

Value	Label
`Default`	Provider default
`Off`	Off
`Low`	Low
`Medium`	Medium
`High`	High