TlsInternalReport

Stores an outbound TLS aggregate report pending delivery.

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

Fields

policyIdentifiers

Type: UnsignedInt[]

Identifiers for the TLS policies that generated this report

mailRua

Type: EmailAddress[]

Reporting email addresses from the TLS policy

httpRua

Type: Uri[]

Reporting URIs from the TLS policy

report

Type: TlsReport · required

TLS report content

domain

Type: DomainName · required

Domain this report is associated with

createdAt

Type: UTCDateTime · required

When the report was created

deliverAt

Type: UTCDateTime · required

When the report is scheduled to be delivered

JMAP API

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

x:TlsInternalReport/get

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

This method requires the sysTlsInternalReportGet permission.

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

x:TlsInternalReport/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 sysTlsInternalReportCreate permission.

curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:TlsInternalReport/set",
          {
            "create": {
              "new1": {
                "createdAt": "2026-01-01T00:00:00Z",
                "deliverAt": "2026-01-01T00:00:00Z",
                "domain": "example.com",
                "httpRua": [],
                "mailRua": [],
                "policyIdentifiers": [],
                "report": {
                  "contactInfo": "Example",
                  "dateRangeEnd": "2026-01-01T00:00:00Z",
                  "dateRangeStart": "2026-01-01T00:00:00Z",
                  "organizationName": "Example",
                  "policies": [],
                  "reportId": "Example"
                }
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

Update

This operation requires the sysTlsInternalReportUpdate permission.

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

Destroy

This operation requires the sysTlsInternalReportDestroy permission.

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

x:TlsInternalReport/query

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

This method requires the sysTlsInternalReportQuery permission.

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

Create

stalwart-cli create tls-internal-report \
  --field 'policyIdentifiers=[]' \
  --field 'mailRua=[]' \
  --field 'httpRua=[]' \
  --field 'report={"contactInfo":"Example","dateRangeEnd":"2026-01-01T00:00:00Z","dateRangeStart":"2026-01-01T00:00:00Z","organizationName":"Example","policies":[],"reportId":"Example"}' \
  --field domain=example.com \
  --field createdAt=2026-01-01T00:00:00Z \
  --field deliverAt=2026-01-01T00:00:00Z

Query

stalwart-cli query tls-internal-report

Update

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

Delete

stalwart-cli delete tls-internal-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