MtaRoute

Defines a routing rule for outbound message delivery.

This object can be configured from the WebUI under Settings › MTA › Outbound › Routes

Fields

MtaRoute 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: "Mx"

Remote Delivery (MX)

ipLookupStrategy

Type: MtaIpStrategy · default: "v4ThenV6"

IP resolution strategy for MX hosts

maxMultihomed

Type: UnsignedInt · default: 2 · min: 1

For multi-homed remote servers, it is the maximum number of IP addresses to try on each delivery attempt

maxMxHosts

Type: UnsignedInt · default: 5 · min: 1

Maximum number of MX hosts to try on each delivery attempt

name

Type: String · read-only

Short identifier for the route

description

Type: String?

A short description of the route, which can be used to identify it in the list of routes

@type: "Relay"

Relay Host

address

Type: HostName · required

The address of the remote SMTP server, which can be an IP address or a domain name

authSecret

Type: SecretKeyOptional · required

The secret to use when authenticating with the remote server

authUsername

Type: String?

The username to use when authenticating with the remote server

port

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

The port number of the remote server, which is typically 25 for SMTP and 11200 for LMTP

protocol

Type: MtaProtocol · default: "smtp"

The protocol to use when delivering messages to the remote server, which can be either SMTP or LMTP

allowInvalidCerts

Type: Boolean · default: false

Whether to allow connections to servers with invalid TLS certificates

implicitTls

Type: Boolean · default: false

Whether to use TLS encryption for all connections to the remote server

name

Type: String · read-only

Short identifier for the route

description

Type: String?

A short description of the route, which can be used to identify it in the list of routes

@type: "Local"

Local Delivery

name

Type: String · read-only

Short identifier for the route

description

Type: String?

A short description of the route, which can be used to identify it in the list of routes

JMAP API

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

x:MtaRoute/get

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

This method requires the sysMtaRouteGet permission.

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

x:MtaRoute/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 sysMtaRouteCreate permission.

curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:MtaRoute/set",
          {
            "create": {
              "new1": {
                "@type": "Mx",
                "description": "Example",
                "ipLookupStrategy": "v4ThenV6",
                "maxMultihomed": 2,
                "maxMxHosts": 5
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

Update

This operation requires the sysMtaRouteUpdate permission.

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

Destroy

This operation requires the sysMtaRouteDestroy permission.

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

x:MtaRoute/query

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

This method requires the sysMtaRouteQuery permission.

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

The x:MtaRoute/query filter argument accepts the following conditions (combinable with AnyOf / AllOf / Not per RFC 8620):

Condition	Kind
name	text

CLI

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

Fetch

stalwart-cli get mta-route id1

Create

stalwart-cli create mta-route/mx \
  --field ipLookupStrategy=v4ThenV6 \
  --field maxMultihomed=2 \
  --field maxMxHosts=5 \
  --field description=Example

Query

stalwart-cli query mta-route
stalwart-cli query mta-route --where name=example

Update

stalwart-cli update mta-route id1 --field description='Updated'

Delete

stalwart-cli delete mta-route --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

Enums

MtaIpStrategy

Value	Label
v4ThenV6	IPv4 then IPv6
v6ThenV4	IPv6 then IPv4
v4Only	IPv4 Only
v6Only	IPv6 Only

MtaProtocol

Value	Label
smtp	SMTP
lmtp	LMTP