Http

Configures HTTP server settings including rate limiting, CORS, and security headers.

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

Fields

rateLimitAuthenticated

Type: Rate? · default: {"count":1000,"period":60000}

Specifies the request rate limit for authenticated users

rateLimitAnonymous

Type: Rate? · default: {"count":100,"period":60000}

Specifies the request rate limit for unauthenticated users

allowedEndpoints

Type: Expression · default: {"else":"200"}

An expression that determines whether access to an endpoint is allowed. The expression should an HTTP status code (200, 403, etc.)

Available variables: HttpVariable.

enableHsts

Type: Boolean · default: false

Specifies whether to enable HTTP Strict Transport Security for the HTTP server.

usePermissiveCors

Type: Boolean · default: false

Specifies whether to allow all origins in the CORS policy for the HTTP server

responseHeaders

Type: Map<String, String>

Additional headers to include in HTTP responses

clientIpSource

Type: ClientIpSource · default: "peer"

Specifies where the client’s IP address is obtained from. When a forwarding header is selected, the listener must only be reachable through the trusted proxies, since any client that connects directly can claim an arbitrary address.

forwardedHops

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

Number of trusted proxy entries appended to the forwarding header; the client address is taken this many entries from the right.

redirectRoot

Type: String? · default: "/account"

The URL to redirect users to when they access the root path of the HTTP server. If not set, the server will return a 404 Not Found response.

JMAP API

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

x:Http/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 sysHttpGet permission.

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

x:Http/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 sysHttpUpdate permission.

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

Update

stalwart-cli update Http --field redirectRoot='updated value'

Nested types

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

Expression

A conditional expression with match rules and a default value.

match

Type: List<ExpressionMatch>

List of conditions and their corresponding results

else

Type: String · required

Else condition

ExpressionMatch

A single condition-result pair in an expression.

if

Type: String · required

If condition

then

Type: String · required

Then clause

Enums

ClientIpSource

Value	Label
peer	TCP peer address
xForwardedFor	X-Forwarded-For header
forwarded	Forwarded header (RFC 7239)

Expression references

The following expression contexts are used by fields on this page:

• HttpVariable (Variables)