SystemSettings

Configures core server settings including hostname and network services.

This object can be configured from the WebUI under Settings › Network › Services, Settings › Network › General

Fields

defaultHostname

Type: HostName · required

The default hostname to use in SMTP greetings, MTA reports and other places where a hostname is needed but not specified.

defaultDomainId

Type: Id<Domain> · required

Default domain to use for authentication and reports.

defaultCertificateId

Type: Id<Certificate>?

Default TLS certificate to use when no SNI is provided by the client

maxConnections

Type: UnsignedInt · default: 8192 · min: 1

The default maximum number of concurrent connections per listener, used by listeners that do not set their own limit

maxBufferedMemory

Type: Size? · min: 16777216

The maximum amount of memory used for buffering messages and blobs in transit. When unset, one quarter of the memory available to the server (the container memory limit if one is set, otherwise physical memory)

proxyTrustedNetworks

Type: Set<IpMask>

Enable proxy protocol for connections from these networks

mailExchangers

Type: List<MailExchanger> · default: {"0":{"priority":10}}

List of mail exchangers to publish in DNS MX records.

services

Type: Map<ServiceProtocol, Service> · default: {"caldav":{"cleartext":false},"carddav":{"cleartext":false},"imap":{"cleartext":false},"jmap":{"cleartext":false},"managesieve":{"cleartext":false},"pop3":{"cleartext":false},"smtp":{"cleartext":false},"webdav":{"cleartext":false}}

List of services to advertise in DNS and auto configuration services

providerInfo

Type: Map<ProviderInfo, String>

Information about the provider to advertise in auto configuration services.

includeSecrets

Type: Boolean · default: false

Include passwords, keys and other secret values in management API responses instead of hiding them. Enable it only to export the configuration and data for a migration, and disable it again afterwards

JMAP API

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

x:SystemSettings/get

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 sysSystemSettingsGet permission.

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

x:SystemSettings/set

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 sysSystemSettingsUpdate permission.

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

Update

stalwart-cli update SystemSettings --field defaultHostname=mail.example.com

Nested types

MailExchanger

Defines a mail exchanger for DNS MX records.

hostname

Type: HostName?

The hostname of the mail exchanger, or null to use the default hostname

priority

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

The priority of the mail exchanger, lower values are preferred. Mail exchangers with the same priority will be selected randomly.

Service

Defines a service endpoint advertised in auto-configuration.

hostname

Type: HostName?

The hostname of the service, or null to use the server’s default hostname

cleartext

Type: Boolean · default: false

Whether to advertise the service as available without TLS encryption. This does not affect whether the service actually accepts cleartext connections, which is configured separately for each network listener.

Enums

ServiceProtocol

Value	Label
jmap	JMAP
imap	IMAP
pop3	POP3
smtp	SMTP submission
caldav	CalDAV
carddav	CardDAV
webdav	WebDAV
managesieve	ManageSieve

ProviderInfo

Value	Label
providerName	Provider name
providerShortName	Short provider name
userDocumentation	URL with user-facing documentation
developerDocumentation	URL with developer-facing documentation
contactUri	Contact information URI
logoUrl	URL to a logo image for the provider
logoWidth	Logo width in pixels
logoHeight	Logo height in pixels