BlockedIp

Defines a blocked IP address or network range.

This object can be configured from the WebUI under Settings › Security › Blocked IPs

Fields

address

Type: IpMask · read-only

The IP address or mask to block

reason

Type: BlockReason · default: "manual"

The reason for blocking this IP address

createdAt

Type: UTCDateTime · server-set

The date and time when this IP address was blocked

expiresAt

Type: UTCDateTime?

The date and time when this IP address block will expire

JMAP API

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

x:BlockedIp/get

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

This method requires the sysBlockedIpGet permission.

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

x:BlockedIp/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 sysBlockedIpCreate permission.

curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:BlockedIp/set",
          {
            "create": {
              "new1": {
                "expiresAt": "2026-01-01T00:00:00Z",
                "reason": "manual"
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

Update

This operation requires the sysBlockedIpUpdate permission.

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

Destroy

This operation requires the sysBlockedIpDestroy permission.

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

x:BlockedIp/query

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

This method requires the sysBlockedIpQuery permission.

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

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

Condition	Kind
address	text

CLI

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

Fetch

stalwart-cli get blocked-ip id1

Create

stalwart-cli create blocked-ip \
  --field reason=manual \
  --field expiresAt=2026-01-01T00:00:00Z

Query

stalwart-cli query blocked-ip
stalwart-cli query blocked-ip --where address=example

Update

stalwart-cli update blocked-ip id1 --field description='Updated'

Delete

stalwart-cli delete blocked-ip --ids id1

Enums

BlockReason

Value	Label
rcptToFailure	Excessive failed RCPT TO commands
authFailure	Excessive failed authentication attempts
loitering	Excessive loitering connections
portScanning	Excessive port scanning attempts
manual	Manually blocked IP address
other	Other reason