Version: 0.16

DnsServer

Defines a DNS server for automatic record management.

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

Fields

DnsServer 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: "Tsig"`

RFC2136 (TSIG)

`host`

Type: IpAddr · required

The IP address of the DNS server

`port`

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

The port used to communicate with the DNS server

`keyName`

Type: String · required

The key used to authenticate with the DNS server

`key`

Type: SecretKey · required

The secret or token used to authenticate with the DNS server

`protocol`

Type: IpProtocol · default: "udp"

The protocol used to communicate with the DNS server

`tsigAlgorithm`

Type: TsigAlgorithm · default: "hmac-sha512"

The TSIG algorithm used to authenticate with the DNS server

`description`

Type: String · required

Short description of this DNS server

`memberTenantId`

Type: Id<Tenant>?

Identifier for the tenant this DNS server belongs to

`timeout`

Type: Duration · default: "30s"

Request timeout for the DNS server

`ttl`

Type: Duration · default: "5m"

The TTL for new DNS record

`pollingInterval`

Type: Duration · default: "15s"

How often to check for DNS records to propagate

`propagationTimeout`

Type: Duration · default: "1m"

How long to wait for DNS records to propagate

`propagationDelay`

Type: Duration?

Initial delay before first propagation check (useful for slow providers)

`@type: "Sig0"`

RFC2136 (SIG0)

`host`

Type: IpAddr · required

The IP address of the DNS server

`port`

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

The port used to communicate with the DNS server

`publicKey`

Type: String · required

The public key used to authenticate with the DNS server

`key`

Type: SecretText · required

The secret or token used to authenticate with the DNS server

`signerName`

Type: String · required

The signer name used in the SIG0 records

`protocol`

Type: IpProtocol · default: "udp"

The protocol used to communicate with the DNS server

`sig0Algorithm`

Type: Sig0Algorithm · default: "ed25519"

The SIG0 algorithm used to authenticate with the DNS server

`description`

Type: String · required

Short description of this DNS server

`memberTenantId`

Type: Id<Tenant>?

Identifier for the tenant this DNS server belongs to

`timeout`

Type: Duration · default: "30s"

Request timeout for the DNS server

`ttl`

Type: Duration · default: "5m"

The TTL for new DNS record

`pollingInterval`

Type: Duration · default: "15s"

How often to check for DNS records to propagate

`propagationTimeout`

Type: Duration · default: "1m"

How long to wait for DNS records to propagate

`propagationDelay`

Type: Duration?

Initial delay before first propagation check (useful for slow providers)

`@type: "Cloudflare"`

Cloudflare

`email`

Type: String?

Optional account email to authenticate with Cloudflare

`secret`

Type: SecretKey · required

The secret or token used to authenticate with the DNS server

`description`

Type: String · required

Short description of this DNS server

`memberTenantId`

Type: Id<Tenant>?

Identifier for the tenant this DNS server belongs to

`timeout`

Type: Duration · default: "30s"

Request timeout for the DNS server

`ttl`

Type: Duration · default: "5m"

The TTL for new DNS record

`pollingInterval`

Type: Duration · default: "15s"

How often to check for DNS records to propagate

`propagationTimeout`

Type: Duration · default: "1m"

How long to wait for DNS records to propagate

`propagationDelay`

Type: Duration?

Initial delay before first propagation check (useful for slow providers)

`@type: "DigitalOcean"`

DigitalOcean

`secret`

Type: SecretKey · required

The secret or token used to authenticate with the DNS server

`description`

Type: String · required

Short description of this DNS server

`memberTenantId`

Type: Id<Tenant>?

Identifier for the tenant this DNS server belongs to

`timeout`

Type: Duration · default: "30s"

Request timeout for the DNS server

`ttl`

Type: Duration · default: "5m"

The TTL for new DNS record

`pollingInterval`

Type: Duration · default: "15s"

How often to check for DNS records to propagate

`propagationTimeout`

Type: Duration · default: "1m"

How long to wait for DNS records to propagate

`propagationDelay`

Type: Duration?

Initial delay before first propagation check (useful for slow providers)

`@type: "DeSEC"`

DeSEC

`secret`

Type: SecretKey · required

The secret or token used to authenticate with the DNS server

`description`

Type: String · required

Short description of this DNS server

`memberTenantId`

Type: Id<Tenant>?

Identifier for the tenant this DNS server belongs to

`timeout`

Type: Duration · default: "30s"

Request timeout for the DNS server

`ttl`

Type: Duration · default: "5m"

The TTL for new DNS record

`pollingInterval`

Type: Duration · default: "15s"

How often to check for DNS records to propagate

`propagationTimeout`

Type: Duration · default: "1m"

How long to wait for DNS records to propagate

`propagationDelay`

Type: Duration?

Initial delay before first propagation check (useful for slow providers)

`@type: "Ovh"`

OVH

`applicationKey`

Type: String · required

The application key used to authenticate with the OVH DNS server

`applicationSecret`

Type: SecretKey · required

The application secret used to authenticate with the OVH DNS server

`consumerKey`

Type: SecretKey · required

The consumer key used to authenticate with the OVH DNS server

`ovhEndpoint`

Type: OvhEndpoint · default: "ovh-eu"

Which OVH endpoint to use

`description`

Type: String · required

Short description of this DNS server

`memberTenantId`

Type: Id<Tenant>?

Identifier for the tenant this DNS server belongs to

`timeout`

Type: Duration · default: "30s"

Request timeout for the DNS server

`ttl`

Type: Duration · default: "5m"

The TTL for new DNS record

`pollingInterval`

Type: Duration · default: "15s"

How often to check for DNS records to propagate

`propagationTimeout`

Type: Duration · default: "1m"

How long to wait for DNS records to propagate

`propagationDelay`

Type: Duration?

Initial delay before first propagation check (useful for slow providers)

`@type: "Bunny"`

BunnyDNS

`secret`

Type: SecretKey · required

The secret or token used to authenticate with the DNS server

`description`

Type: String · required

Short description of this DNS server

`memberTenantId`

Type: Id<Tenant>?

Identifier for the tenant this DNS server belongs to

`timeout`

Type: Duration · default: "30s"

Request timeout for the DNS server

`ttl`

Type: Duration · default: "5m"

The TTL for new DNS record

`pollingInterval`

Type: Duration · default: "15s"

How often to check for DNS records to propagate

`propagationTimeout`

Type: Duration · default: "1m"

How long to wait for DNS records to propagate

`propagationDelay`

Type: Duration?

Initial delay before first propagation check (useful for slow providers)

`@type: "Porkbun"`

Porkbun

`apiKey`

Type: String · required

The API key used to authenticate with Porkbun

`secretApiKey`

Type: SecretKey · required

The secret API key used to authenticate with Porkbun

`secret`

Type: SecretKey · required

The secret or token used to authenticate with the DNS server

`description`

Type: String · required

Short description of this DNS server

`memberTenantId`

Type: Id<Tenant>?

Identifier for the tenant this DNS server belongs to

`timeout`

Type: Duration · default: "30s"

Request timeout for the DNS server

`ttl`

Type: Duration · default: "5m"

The TTL for new DNS record

`pollingInterval`

Type: Duration · default: "15s"

How often to check for DNS records to propagate

`propagationTimeout`

Type: Duration · default: "1m"

How long to wait for DNS records to propagate

`propagationDelay`

Type: Duration?

Initial delay before first propagation check (useful for slow providers)

`@type: "Dnsimple"`

DNSimple

`authToken`

Type: SecretKey · required

The authentication token used to authenticate with DNSimple

`accountIdentifier`

Type: String · required

The account ID used to authenticate with DNSimple

`secret`

Type: SecretKey · required

The secret or token used to authenticate with the DNS server

`description`

Type: String · required

Short description of this DNS server

`memberTenantId`

Type: Id<Tenant>?

Identifier for the tenant this DNS server belongs to

`timeout`

Type: Duration · default: "30s"

Request timeout for the DNS server

`ttl`

Type: Duration · default: "5m"

The TTL for new DNS record

`pollingInterval`

Type: Duration · default: "15s"

How often to check for DNS records to propagate

`propagationTimeout`

Type: Duration · default: "1m"

How long to wait for DNS records to propagate

`propagationDelay`

Type: Duration?

Initial delay before first propagation check (useful for slow providers)

`@type: "Spaceship"`

Spaceship

`apiKey`

Type: String · required

The API key used to authenticate with Spaceship

`secret`

Type: SecretKey · required

The secret or token used to authenticate with the DNS server

`description`

Type: String · required

Short description of this DNS server

`memberTenantId`

Type: Id<Tenant>?

Identifier for the tenant this DNS server belongs to

`timeout`

Type: Duration · default: "30s"

Request timeout for the DNS server

`ttl`

Type: Duration · default: "5m"

The TTL for new DNS record

`pollingInterval`

Type: Duration · default: "15s"

How often to check for DNS records to propagate

`propagationTimeout`

Type: Duration · default: "1m"

How long to wait for DNS records to propagate

`propagationDelay`

Type: Duration?

Initial delay before first propagation check (useful for slow providers)

`@type: "Route53"`

AWS Route53

`accessKeyId`

Type: String · required

The AWS access key ID

`secretAccessKey`

Type: SecretKey · required

The AWS secret access key

`sessionToken`

Type: SecretKeyOptional · required

Optional session token for temporary AWS credentials

`region`

Type: String · default: "us-east-1"

The AWS region

`hostedZoneId`

Type: String?

Hosted zone ID to use (resolved automatically by name if not set)

`privateZoneOnly`

Type: Boolean · default: false

Whether to restrict zone resolution to private zones only

`description`

Type: String · required

Short description of this DNS server

`memberTenantId`

Type: Id<Tenant>?

Identifier for the tenant this DNS server belongs to

`timeout`

Type: Duration · default: "30s"

Request timeout for the DNS server

`ttl`

Type: Duration · default: "5m"

The TTL for new DNS record

`pollingInterval`

Type: Duration · default: "15s"

How often to check for DNS records to propagate

`propagationTimeout`

Type: Duration · default: "1m"

How long to wait for DNS records to propagate

`propagationDelay`

Type: Duration?

Initial delay before first propagation check (useful for slow providers)

`@type: "GoogleCloudDns"`

Google Cloud DNS

`serviceAccountJson`

Type: SecretText · required

Service account JSON credentials used to authenticate with Google Cloud

`projectId`

Type: String · required

The Google Cloud project ID that owns the managed zone

`managedZone`

Type: String?

Managed zone name (resolved automatically by longest suffix match if not set)

`privateZone`

Type: Boolean · default: false

Whether to restrict zone resolution to private zones only

`impersonateServiceAccount`

Type: String?

Optional service account email to impersonate

`description`

Type: String · required

Short description of this DNS server

`memberTenantId`

Type: Id<Tenant>?

Identifier for the tenant this DNS server belongs to

`timeout`

Type: Duration · default: "30s"

Request timeout for the DNS server

`ttl`

Type: Duration · default: "5m"

The TTL for new DNS record

`pollingInterval`

Type: Duration · default: "15s"

How often to check for DNS records to propagate

`propagationTimeout`

Type: Duration · default: "1m"

How long to wait for DNS records to propagate

`propagationDelay`

Type: Duration?

Initial delay before first propagation check (useful for slow providers)

JMAP API

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

`x:DnsServer/get`

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

This method requires the sysDnsServerGet permission.

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

`x:DnsServer/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 sysDnsServerCreate permission.

curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:DnsServer/set",
          {
            "create": {
              "new1": {
                "@type": "Tsig",
                "description": "Example",
                "host": "192.0.2.1",
                "key": {
                  "@type": "Value",
                  "secret": "Example"
                },
                "keyName": "Example",
                "memberTenantId": "<Tenant id>",
                "pollingInterval": "15s",
                "port": 53,
                "propagationDelay": 1000,
                "propagationTimeout": "1m",
                "protocol": "udp",
                "timeout": "30s",
                "tsigAlgorithm": "hmac-sha512",
                "ttl": "5m"
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

Update

This operation requires the sysDnsServerUpdate permission.

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

Destroy

This operation requires the sysDnsServerDestroy permission.

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

`x:DnsServer/query`

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

This method requires the sysDnsServerQuery permission.

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

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

Condition	Kind
`memberTenantId`	id of Tenant

CLI

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

Fetch

stalwart-cli get dns-server id1

Create

stalwart-cli create dns-server/tsig \
  --field host=192.0.2.1 \
  --field port=53 \
  --field keyName=Example \
  --field 'key={"@type":"Value","secret":"Example"}' \
  --field protocol=udp \
  --field tsigAlgorithm=hmac-sha512 \
  --field description=Example \
  --field 'memberTenantId=<Tenant id>' \
  --field timeout=30s \
  --field ttl=5m \
  --field pollingInterval=15s \
  --field propagationTimeout=1m \
  --field propagationDelay=1000

Query

stalwart-cli query dns-server
stalwart-cli query dns-server --where memberTenantId=id1

Update

stalwart-cli update dns-server id1 --field description='Updated'

Delete

stalwart-cli delete dns-server --ids id1

Nested types

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

SecretText

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

Text: Secret value. Carries the fields of SecretTextValue.
EnvironmentVariable: Secret read from environment variable. Carries the fields of SecretKeyEnvironmentVariable.
File: Secret read from file. Carries the fields of SecretKeyFile.

SecretTextValue

A secret text value provided directly.

`secret`

Type: Text · required · secret

Password or secret value

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.

Enums

IpProtocol

Value	Label
`udp`	UDP
`tcp`	TCP

TsigAlgorithm

Value	Label
`hmac-md5`	HMAC-MD5
`gss`	GSS
`hmac-sha1`	HMAC-SHA1
`hmac-sha224`	HMAC-SHA224
`hmac-sha256`	HMAC-SHA256
`hmac-sha256-128`	HMAC-SHA256-128
`hmac-sha384`	HMAC-SHA384
`hmac-sha384-192`	HMAC-SHA384-192
`hmac-sha512`	HMAC-SHA512
`hmac-sha512-256`	HMAC-SHA512-256

Sig0Algorithm

Value	Label
`ecdsa-p256-sha256`	ECDSA-P256-SHA256
`ecdsa-p384-sha384`	ECDSA-P384-SHA384
`ed25519`	ED25519

OvhEndpoint

Value	Label
`ovh-eu`	OVH EU
`ovh-ca`	OVH CA
`kimsufi-eu`	Kimsufi EU
`kimsufi-ca`	Kimsufi CA
`soyoustart-eu`	Soyoustart EU
`soyoustart-ca`	Soyoustart CA

Fields​

@type: "Tsig"​

host​

port​

keyName​

key​

protocol​

tsigAlgorithm​

description​

memberTenantId​

timeout​

ttl​

pollingInterval​

propagationTimeout​

propagationDelay​

@type: "Sig0"​

host​

port​

publicKey​

key​

signerName​

protocol​

sig0Algorithm​

description​

memberTenantId​

timeout​

ttl​

pollingInterval​

propagationTimeout​

propagationDelay​

@type: "Cloudflare"​

email​

secret​

description​

memberTenantId​

timeout​

ttl​

pollingInterval​

propagationTimeout​

propagationDelay​

@type: "DigitalOcean"​

secret​

description​

memberTenantId​

timeout​

ttl​

pollingInterval​

propagationTimeout​

propagationDelay​

@type: "DeSEC"​

secret​

description​

memberTenantId​

timeout​

ttl​

pollingInterval​

propagationTimeout​

propagationDelay​

@type: "Ovh"​

applicationKey​

applicationSecret​

consumerKey​

ovhEndpoint​

description​

memberTenantId​

timeout​

ttl​

pollingInterval​

propagationTimeout​

propagationDelay​

@type: "Bunny"​

secret​

description​

memberTenantId​

timeout​

ttl​

pollingInterval​

propagationTimeout​

propagationDelay​

@type: "Porkbun"​

Fields

`@type: "Tsig"`

`host`

`port`

`keyName`

`key`

`protocol`

`tsigAlgorithm`

`description`

`memberTenantId`

`timeout`

`ttl`

`pollingInterval`

`propagationTimeout`

`propagationDelay`

`@type: "Sig0"`

`host`

`port`

`publicKey`

`key`

`signerName`

`protocol`

`sig0Algorithm`

`description`

`memberTenantId`

`timeout`

`ttl`

`pollingInterval`

`propagationTimeout`

`propagationDelay`

`@type: "Cloudflare"`

`email`

`secret`

`description`

`memberTenantId`

`timeout`

`ttl`

`pollingInterval`

`propagationTimeout`

`propagationDelay`

`@type: "DigitalOcean"`

`secret`

`description`

`memberTenantId`

`timeout`

`ttl`

`pollingInterval`

`propagationTimeout`

`propagationDelay`

`@type: "DeSEC"`

`secret`

`description`

`memberTenantId`

`timeout`

`ttl`

`pollingInterval`

`propagationTimeout`

`propagationDelay`

`@type: "Ovh"`

`applicationKey`

`applicationSecret`

`consumerKey`

`ovhEndpoint`

`description`

`memberTenantId`

`timeout`

`ttl`

`pollingInterval`

`propagationTimeout`

`propagationDelay`

`@type: "Bunny"`

`secret`

`description`

`memberTenantId`

`timeout`

`ttl`

`pollingInterval`

`propagationTimeout`

`propagationDelay`

`@type: "Porkbun"`