MtaHook

MtaHook

Defines an MTA hook endpoint for message processing.

This object can be configured from the WebUI under Settings › MTA › Filters › MTA Hooks

Fields

allowInvalidCerts

Type: Boolean · default: false

Whether Stalwart should connect to a hook server that has an invalid TLS certificate

enable

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

Expression that determines whether to enable this hook

Available variables: MtaRcptToVariable.

maxResponseSize

Type: Size · default: 52428800

Maximum size, in bytes, of a response that Stalwart will accept from this MTA Hook server

tempFailOnError

Type: Boolean · default: true

Whether to respond with a temporary failure (typically a 4xx SMTP status code) when Stalwart encounters an error while communicating with this MTA Hook server

stages

Type: MtaStage[] · default: ["data"]

Which SMTP stages to run this hook on

timeout

Type: Duration · default: "30s"

Maximum amount of time that Stalwart will wait for a response from this hook server

url

Type: Uri · required

URL of the hook endpoint

httpAuth

Type: HttpAuth · required

The type of HTTP authentication to use

httpHeaders

Type: Map<String, String>

Additional headers to include in HTTP requests

JMAP API

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

x:MtaHook/get

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

This method requires the sysMtaHookGet permission.

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

x:MtaHook/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 sysMtaHookCreate permission.

curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:MtaHook/set",
          {
            "create": {
              "new1": {
                "httpAuth": {
                  "@type": "Unauthenticated"
                },
                "httpHeaders": {},
                "url": "https://example.com"
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

Update

This operation requires the sysMtaHookUpdate permission.

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

Destroy

This operation requires the sysMtaHookDestroy permission.

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

x:MtaHook/query

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

This method requires the sysMtaHookQuery permission.

curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:MtaHook/query",
          {
            "filter": {}
          },
          "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 MtaHook id1

Create

stalwart-cli create MtaHook \
  --field url=https://example.com \
  --field 'httpAuth={"@type":"Unauthenticated"}' \
  --field 'httpHeaders={}'

Query

stalwart-cli query MtaHook

Update

stalwart-cli update MtaHook id1 --field allowInvalidCerts=false

Delete

stalwart-cli delete MtaHook --ids id1

Nested types

Expression

A conditional expression with match rules and a default value.

match

Type: 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

HttpAuth

Defines the HTTP authentication method to use for HTTP requests.

• Unauthenticated: Anonymous. No additional fields.
• Basic: Basic Authentication. Carries the fields of HttpAuthBasic.
• Bearer: Bearer Token. Carries the fields of HttpAuthBearer.

HttpAuthBasic

HTTP Basic authentication credentials.

username

Type: String · required

Username for HTTP Basic Authentication

secret

Type: SecretKey · required

Password for HTTP Basic Authentication

SecretKey

A secret value provided directly, from an environment variable, or from a file.

• 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

HttpAuthBearer

HTTP Bearer token authentication.

bearerToken

Type: SecretKey · required

Bearer token for HTTP Bearer Authentication

Enums

MtaStage

Value	Label
connect	Connect
ehlo	EHLO
auth	AUTH
mail	MAIL FROM
rcpt	RCPT TO
data	DATA

Expression references

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

• MtaRcptToVariable (Variables)