Version: 0.16

NetworkListener

Defines a network listener for accepting incoming connections.

This object can be configured from the WebUI under Settings › Network › Listeners

Fields

`name`

Type: String · read-only

Unique identifier for the listener

`bind`

Type: SocketAddr[] · min items: 1

The addresses the listener will bind to

`protocol`

Type: NetworkListenerProtocol · default: "smtp"

The protocol used by the listener

`overrideProxyTrustedNetworks`

Type: IpMask[]

Enable proxy protocol for connections from these networks

`socketBacklog`

Type: UnsignedInt? · default: 1024 · min: 1

The maximum number of incoming connections that can be pending in the backlog queue

`socketNoDelay`

Type: Boolean · default: true

Whether the Nagle algorithm should be disabled for the socket

`socketReceiveBufferSize`

Type: UnsignedInt? · min: 1

The size of the buffer used for receiving data

`socketReuseAddress`

Type: Boolean · default: true

Whether the socket can be bound to an address that is already in use by another socket

`socketReusePort`

Type: Boolean · default: true

Whether multiple sockets can be bound to the same address and port

`socketSendBufferSize`

Type: UnsignedInt? · min: 1

The size of the buffer used for sending data

`socketTosV4`

Type: UnsignedInt? · min: 1

The type of service (TOS) value for the socket, which determines the priority of the traffic sent through the socket

`socketTtl`

Type: UnsignedInt? · min: 1

Time-to-live (TTL) value for the socket, which determines how many hops a packet can make before it is discarded

`useTls`

Type: Boolean · default: true

Whether to enable TLS for this listener

`tlsDisableCipherSuites`

Type: TlsCipherSuite[]

Which cipher suites to disable

`tlsDisableProtocols`

Type: TlsVersion[]

Which TLS protocols to disable

`tlsIgnoreClientOrder`

Type: Boolean · default: true

Whether to ignore the client's cipher order

`tlsImplicit`

Type: Boolean · default: false

Whether to use implicit TLS

`tlsTimeout`

Type: Duration? · default: "1m"

TLS handshake timeout

`maxConnections`

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

The maximum number of concurrent connections the listener will accept

JMAP API

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

`x:NetworkListener/get`

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

This method requires the sysNetworkListenerGet permission.

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

`x:NetworkListener/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 sysNetworkListenerCreate permission.

curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:NetworkListener/set",
          {
            "create": {
              "new1": {
                "bind": [],
                "maxConnections": 8192,
                "overrideProxyTrustedNetworks": [],
                "protocol": "smtp",
                "socketBacklog": 1024,
                "socketNoDelay": true,
                "socketReceiveBufferSize": 1000,
                "socketReuseAddress": true,
                "socketReusePort": true,
                "socketSendBufferSize": 1000,
                "socketTosV4": 1000,
                "socketTtl": 1000,
                "tlsDisableCipherSuites": [],
                "tlsDisableProtocols": [],
                "tlsIgnoreClientOrder": true,
                "tlsImplicit": false,
                "tlsTimeout": "1m",
                "useTls": true
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

Update

This operation requires the sysNetworkListenerUpdate permission.

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

Destroy

This operation requires the sysNetworkListenerDestroy permission.

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

`x:NetworkListener/query`

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

This method requires the sysNetworkListenerQuery permission.

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

The x:NetworkListener/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 network-listener id1

Create

stalwart-cli create network-listener \
  --field 'bind=[]' \
  --field protocol=smtp \
  --field 'overrideProxyTrustedNetworks=[]' \
  --field socketBacklog=1024 \
  --field socketNoDelay=true \
  --field socketReceiveBufferSize=1000 \
  --field socketReuseAddress=true \
  --field socketReusePort=true \
  --field socketSendBufferSize=1000 \
  --field socketTosV4=1000 \
  --field socketTtl=1000 \
  --field useTls=true \
  --field 'tlsDisableCipherSuites=[]' \
  --field 'tlsDisableProtocols=[]' \
  --field tlsIgnoreClientOrder=true \
  --field tlsImplicit=false \
  --field tlsTimeout=1m \
  --field maxConnections=8192

Query

stalwart-cli query network-listener
stalwart-cli query network-listener --where name=example

Update

stalwart-cli update network-listener id1 --field description='Updated'

Delete

stalwart-cli delete network-listener --ids id1

Enums