Version: 0.16

Domain

Defines an email domain and its DNS, DKIM, and TLS certificate settings.

This object can be configured from the WebUI under Management › Domains › Domains

Fields

`name`

Type: DomainName · required

Domain name

`aliases`

Type: DomainName[]

List of additional domain names that are aliases of this domain

`isEnabled`

Type: Boolean · default: true

Whether this domain is enabled

`createdAt`

Type: UTCDateTime · read-only · server-set

Creation date of the domain

`description`

Type: String?

Description of the domain

`logo`

Type: String? · enterprise

URL or base64-encoded image representing the domain

`certificateManagement`

Type: CertificateManagement · required

Whether TLS certificates for this domain are managed manually or automatically by an ACME provider

`dkimManagement`

Type: DkimManagement · required

Whether DKIM keys for this domain are managed manually or automatically by the server

`dnsManagement`

Type: DnsManagement · required

Whether DNS records for this domain are managed manually or automatically by a DNS provider

`dnsZoneFile`

Type: Text · server-set

Current DNS zone data for the domain

`memberTenantId`

Type: Id<Tenant>? · enterprise

Identifier for the tenant this domain belongs to

`directoryId`

Type: Id<Directory>? · enterprise

Identifier for the directory where accounts for this domain are stored, or null to use the internal directory

`catchAllAddress`

Type: EmailAddress?

Catch-all email address that receives messages addressed to unknown local recipients

`subAddressing`

Type: SubAddressing · required

Whether sub-addressing (plus addressing) is enabled for the domain

`allowRelaying`

Type: Boolean · default: false

Whether to allow relaying for non-local recipients, useful in split delivery scenarios

`reportAddressUri`

Type: String? · default: "mailto:postmaster"

Email address to receive DMARC, TLS-RPT and CAA reports for this domain, or null to not receive reports

JMAP API

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

`x:Domain/get`

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

This method requires the sysDomainGet permission.

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

`x:Domain/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 sysDomainCreate permission.

curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:Domain/set",
          {
            "create": {
              "new1": {
                "aliases": [],
                "allowRelaying": false,
                "catchAllAddress": "[email protected]",
                "certificateManagement": {
                  "@type": "Manual"
                },
                "description": "Example",
                "directoryId": "<Directory id>",
                "dkimManagement": {
                  "@type": "Automatic",
                  "algorithms": [
                    "Dkim1Ed25519Sha256",
                    "Dkim1RsaSha256"
                  ],
                  "deleteAfter": "30d",
                  "retireAfter": "7d",
                  "rotateAfter": "90d",
                  "selectorTemplate": "v{version}-{algorithm}-{date-%Y%m%d}"
                },
                "dnsManagement": {
                  "@type": "Manual"
                },
                "isEnabled": true,
                "logo": "Example",
                "memberTenantId": "<Tenant id>",
                "name": "example.com",
                "reportAddressUri": "mailto:postmaster",
                "subAddressing": {
                  "@type": "Enabled"
                }
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

Update

This operation requires the sysDomainUpdate permission.

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

Destroy

This operation requires the sysDomainDestroy permission.

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

`x:Domain/query`

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

This method requires the sysDomainQuery permission.

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

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

Condition	Kind
`text`	text
`name`	text
`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 domain id1

Create

stalwart-cli create domain \
  --field name=example.com \
  --field 'aliases=[]' \
  --field isEnabled=true \
  --field description=Example \
  --field logo=Example \
  --field 'certificateManagement={"@type":"Manual"}' \
  --field 'dkimManagement={"@type":"Automatic","algorithms":["Dkim1Ed25519Sha256","Dkim1RsaSha256"],"deleteAfter":"30d","retireAfter":"7d","rotateAfter":"90d","selectorTemplate":"v{version}-{algorithm}-{date-%Y%m%d}"}' \
  --field 'dnsManagement={"@type":"Manual"}' \
  --field 'memberTenantId=<Tenant id>' \
  --field 'directoryId=<Directory id>' \
  --field [email protected] \
  --field 'subAddressing={"@type":"Enabled"}' \
  --field allowRelaying=false \
  --field reportAddressUri=mailto:postmaster

Query

stalwart-cli query domain
stalwart-cli query domain --where text=example

Update

stalwart-cli update domain id1 --field description='Updated'

Delete

stalwart-cli delete domain --ids id1

Nested types

CertificateManagement

Defines how TLS certificates for the domain are managed.

Manual: Manual TLS certificate management. No additional fields.
Automatic: ACME TLS certificate management. Carries the fields of CertificateManagementProperties.

CertificateManagementProperties

Automatic TLS certificate management settings using an ACME provider.

`acmeProviderId`

Type: Id<AcmeProvider> · required

Identifier for the ACME provider managing certificates for this domain

`subjectAlternativeNames`

Type: String[]

Additional hostnames to include in the certificate besides the domain name itself. Leave empty to request wildcard certificates when possible, or to use the default set of SANs.

DkimManagement

Defines how DKIM keys for the domain are managed.

Automatic: Automatic DKIM management. Carries the fields of DkimManagementProperties.
Manual: Manual DKIM management. No additional fields.

DkimManagementProperties

Automatic DKIM key generation and rotation settings.

`algorithms`

Type: DkimSignatureType[] · default: ["Dkim1Ed25519Sha256","Dkim1RsaSha256"]

List of signing algorithms to use when generating new DKIM keys

`selectorTemplate`

Type: String · default: "v{version}-{algorithm}-{date-%Y%m%d}"

Template for generating DKIM selectors during key rotation. Supported variables:

{algorithm}: signing algorithm in lowercase (rsa, ed25519)

{hash}: hash algorithm (sha256)

{version}: DKIM version number (1)

{date-<fmt>}: current UTC date formatted with chrono strftime (e.g. {date-%Y%m%d})

{epoch}: current UTC unix timestamp

{random}: random 8-character alphanumeric string

`rotateAfter`

Type: Duration · default: "90d"

How often to rotate DKIM keys. Requires automatic DNS management to be enabled for the domain.

`retireAfter`

Type: Duration · default: "7d"

How long to keep the old key's DNS record published after rotation before removing it. Requires automatic DNS management.

`deleteAfter`

Type: Duration · default: "30d"

How long to retain old DKIM keys on the server after rotation before deleting them permanently. Requires automatic DNS management.

DnsManagement

Defines how DNS records for the domain are managed.

Manual: Manual DNS management. No additional fields.
Automatic: Automatic DNS management. Carries the fields of DnsManagementProperties.

DnsManagementProperties

Automatic DNS record management settings using a DNS provider.

`dnsServerId`

Type: Id<DnsServer> · required

Identifier for the DNS server provider managing DNS records for this domain

`origin`

Type: String?

Origin domain used to determine the correct DNS zone for managing records. For example, if the domain is "sub.example.com" and DNS records should be managed in the "example.com" zone, set the origin to "example.com". Leave empty to use the domain name itself as the zone origin.

`publishRecords`

Type: DnsRecordType[] · default: ["dkim","spf","mx","dmarc","srv","mtaSts","tlsRpt","caa","autoConfig","autoConfigLegacy","autoDiscover"] · min items: 1

Which DNS record types should be automatically published and kept in sync

SubAddressing

Defines sub-addressing (plus addressing) settings for the domain.

Enabled: Enable sub-addressing. No additional fields.
Custom: Enable custom sub-addressing. Carries the fields of SubAddressingCustom.
Disabled: Disable sub-addressing. No additional fields.

SubAddressingCustom

Custom sub-addressing rules for the domain.

`customRule`

Type: Expression · required

Expression that defines custom sub-addressing rules for the domain

Available variables: MtaRcptVariable.

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

Enums

DkimSignatureType

Value	Label
`Dkim1Ed25519Sha256`	DKIM1 - Ed25519 SHA-256
`Dkim1RsaSha256`	DKIM1 - RSA SHA-256

DnsRecordType

Value	Label
`dkim`	DKIM public keys
`tlsa`	TLSA records
`spf`	SPF records
`mx`	MX records
`dmarc`	DMARC policy
`srv`	SRV records
`mtaSts`	MTA-STS policy record
`tlsRpt`	TLS reporting record
`caa`	CAA records
`autoConfig`	Autoconfig records
`autoConfigLegacy`	Legacy Autoconfig records
`autoDiscover`	Microsoft Autodiscover records

Expression references

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

MtaRcptVariable (Variables)

Fields​

name​

aliases​

isEnabled​

createdAt​

description​

logo​

certificateManagement​

dkimManagement​

dnsManagement​

dnsZoneFile​

memberTenantId​

directoryId​

catchAllAddress​

subAddressing​

allowRelaying​

reportAddressUri​

JMAP API​

x:Domain/get​

x:Domain/set​

Create​

Update​

Destroy​

x:Domain/query​

CLI​

Fetch​

Create​

Query​

Update​

Delete​

Nested types​

CertificateManagement​

CertificateManagementProperties​

acmeProviderId​

subjectAlternativeNames​

DkimManagement​

DkimManagementProperties​

algorithms​

selectorTemplate​

rotateAfter​

retireAfter​

deleteAfter​

DnsManagement​

DnsManagementProperties​

dnsServerId​

origin​

publishRecords​

SubAddressing​

SubAddressingCustom​

customRule​

Expression​

match​

else​

ExpressionMatch​

if​

then​

Enums​

DkimSignatureType​

DnsRecordType​

Expression references​

Fields

`name`

`aliases`

`isEnabled`

`createdAt`

`description`

`logo`

`certificateManagement`

`dkimManagement`

`dnsManagement`

`dnsZoneFile`

`memberTenantId`

`directoryId`

`catchAllAddress`

`subAddressing`

`allowRelaying`

`reportAddressUri`

JMAP API

`x:Domain/get`

`x:Domain/set`

Create

Update

Destroy

`x:Domain/query`

CLI

Fetch

Create

Query

Update

Delete

Nested types

CertificateManagement

CertificateManagementProperties

`acmeProviderId`

`subjectAlternativeNames`

DkimManagement

DkimManagementProperties

`algorithms`

`selectorTemplate`

`rotateAfter`

`retireAfter`

`deleteAfter`

DnsManagement

DnsManagementProperties

`dnsServerId`

`origin`

`publishRecords`

SubAddressing

SubAddressingCustom

`customRule`

Expression

`match`

`else`

ExpressionMatch

`if`

`then`

Enums

DkimSignatureType

DnsRecordType

Expression references