TlsExternalReport

Stores a TLS aggregate report received from an external source.

This object can be configured from the WebUI under Management › Reports › Inbox › TLS

Fields

report

Type: TlsReport · required

TLS report content

from

Type: EmailAddress · required

Email address of the report sender

subject

Type: String · required

Subject line of the report email

to

Type: EmailAddress[]

List of recipient email addresses

receivedAt

Type: UTCDateTime · required

When the report email was received

expiresAt

Type: UTCDateTime · required

When the report is scheduled to be deleted

memberTenantId

Type: Id<Tenant>? · enterprise

Identifier for the tenant this report belongs to

JMAP API

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

x:TlsExternalReport/get

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

This method requires the sysTlsExternalReportGet permission.

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

x:TlsExternalReport/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 sysTlsExternalReportCreate permission.

curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:TlsExternalReport/set",
          {
            "create": {
              "new1": {
                "expiresAt": "2026-01-01T00:00:00Z",
                "from": "[email protected]",
                "memberTenantId": "<Tenant id>",
                "receivedAt": "2026-01-01T00:00:00Z",
                "report": {
                  "contactInfo": "Example",
                  "dateRangeEnd": "2026-01-01T00:00:00Z",
                  "dateRangeStart": "2026-01-01T00:00:00Z",
                  "organizationName": "Example",
                  "policies": [],
                  "reportId": "Example"
                },
                "subject": "Example",
                "to": []
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

Update

This operation requires the sysTlsExternalReportUpdate permission.

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

Destroy

This operation requires the sysTlsExternalReportDestroy permission.

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

x:TlsExternalReport/query

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

This method requires the sysTlsExternalReportQuery permission.

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

Create

stalwart-cli create tls-external-report \
  --field 'report={"contactInfo":"Example","dateRangeEnd":"2026-01-01T00:00:00Z","dateRangeStart":"2026-01-01T00:00:00Z","organizationName":"Example","policies":[],"reportId":"Example"}' \
  --field [email protected] \
  --field subject=Example \
  --field 'to=[]' \
  --field receivedAt=2026-01-01T00:00:00Z \
  --field expiresAt=2026-01-01T00:00:00Z \
  --field 'memberTenantId=<Tenant id>'

Query

stalwart-cli query tls-external-report

Update

stalwart-cli update tls-external-report id1 --field description='Updated'

Delete

stalwart-cli delete tls-external-report --ids id1

Nested types

TlsReport

Content of a TLS aggregate report.

organizationName

Type: String?

Name of the organization that generated the report

contactInfo

Type: String?

Contact information for the reporting organization

reportId

Type: String · required

Unique identifier for this report

dateRangeStart

Type: UTCDateTime · required

Start of the reporting period

dateRangeEnd

Type: UTCDateTime · required

End of the reporting period

policies

Type: TlsReportPolicy[]

Policy evaluation results for each domain

TlsReportPolicy

TLS policy evaluation result for a specific domain.

policyType

Type: TlsPolicyType · required

Type of TLS policy that was evaluated

policyStrings

Type: String[]

Raw policy strings as retrieved

policyDomain

Type: DomainName · required

Domain the policy applies to

mxHosts

Type: String[]

MX hostnames covered by the policy

totalSuccessfulSessions

Type: UnsignedInt · default: 0

Number of sessions that successfully established TLS

totalFailedSessions

Type: UnsignedInt · default: 0

Number of sessions that failed TLS establishment

failureDetails

Type: TlsFailureDetails[]

Details of TLS failures encountered

TlsFailureDetails

Details of a TLS failure encountered during delivery.

resultType

Type: TlsResultType · required

Type of failure encountered

sendingMtaIp

Type: IpAddr?

IP address of the sending mail server

receivingMxHostname

Type: String?

Hostname of the receiving mail server

receivingMxHelo

Type: String?

HELO/EHLO string of the receiving mail server

receivingIp

Type: IpAddr?

IP address of the receiving mail server

failedSessionCount

Type: UnsignedInt · default: 0

Number of sessions that failed with this error

additionalInformation

Type: String?

Additional context about the failure

failureReasonCode

Type: String?

Error code or reason string for the failure

Enums

TlsPolicyType

Value	Label
tlsa	DANE TLSA policy
sts	MTA-STS policy
noPolicyFound	No TLS policy was found for the domain
other	Other or unrecognized policy type

TlsResultType

Value	Label
startTlsNotSupported	Remote server does not support STARTTLS
certificateHostMismatch	Certificate hostname does not match server
certificateExpired	Certificate has expired
certificateNotTrusted	Certificate is not trusted
validationFailure	General certificate validation failure
tlsaInvalid	DANE TLSA record is invalid
dnssecInvalid	DNSSEC validation failed
daneRequired	DANE is required but not available
stsPolicyFetchError	Failed to fetch MTA-STS policy
stsPolicyInvalid	MTA-STS policy is invalid
stsWebpkiInvalid	MTA-STS WebPKI validation failed
other	Other or unrecognized failure type