DmarcExternalReport

Stores a DMARC aggregate report received from an external source.

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

Fields

`report`

Type: DmarcReport · required

DMARC 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 DmarcExternalReport object is available via the urn:stalwart:jmap capability.

`x:DmarcExternalReport/get`

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

This method requires the sysDmarcExternalReportGet permission.

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

`x:DmarcExternalReport/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 sysDmarcExternalReportCreate permission.

curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:DmarcExternalReport/set",
          {
            "create": {
              "new1": {
                "expiresAt": "2026-01-01T00:00:00Z",
                "from": "[email protected]",
                "receivedAt": "2026-01-01T00:00:00Z",
                "report": {
                  "dateRangeBegin": "2026-01-01T00:00:00Z",
                  "dateRangeEnd": "2026-01-01T00:00:00Z",
                  "email": "[email protected]",
                  "errors": {},
                  "extensions": {},
                  "orgName": "Example",
                  "policyAdkim": "relaxed",
                  "policyAspf": "relaxed",
                  "policyDisposition": "none",
                  "policyDomain": "Example",
                  "policyFailureReportingOptions": {},
                  "policySubdomainDisposition": "none",
                  "records": {},
                  "reportId": "Example"
                },
                "subject": "Example",
                "to": {}
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

Update

This operation requires the sysDmarcExternalReportUpdate permission.

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

Destroy

This operation requires the sysDmarcExternalReportDestroy permission.

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

`x:DmarcExternalReport/query`

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

This method requires the sysDmarcExternalReportQuery permission.

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

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

Condition	Kind
`domain`	text
`totalFailedSessions`	integer
`totalSuccessfulSessions`	integer
`expiresAt`	date
`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 DmarcExternalReport id1

Create

stalwart-cli create DmarcExternalReport \
  --field 'report={"dateRangeBegin":"2026-01-01T00:00:00Z","dateRangeEnd":"2026-01-01T00:00:00Z","email":"[email protected]","errors":{},"extensions":{},"orgName":"Example","policyAdkim":"relaxed","policyAspf":"relaxed","policyDisposition":"none","policyDomain":"Example","policyFailureReportingOptions":{},"policySubdomainDisposition":"none","records":{},"reportId":"Example"}' \
  --field [email protected] \
  --field subject=Example \
  --field 'to={}' \
  --field receivedAt=2026-01-01T00:00:00Z \
  --field expiresAt=2026-01-01T00:00:00Z

Query

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

Update

stalwart-cli update DmarcExternalReport id1 --field subject='updated value'

Delete

stalwart-cli delete DmarcExternalReport --ids id1

Nested types

DmarcReport

Content of a DMARC aggregate report.

`version`

Type: Float · default: 1.0

DMARC report format version

`orgName`

Type: String · required

Name of the organization that generated the report

`email`

Type: EmailAddress · required

Contact email address of the reporting organization

`extraContactInfo`

Type: String?

Additional contact information for the reporting organization

`reportId`

Type: String · required

Unique identifier for this report

`dateRangeBegin`

Type: UTCDateTime · required

Start of the reporting period

`dateRangeEnd`

Type: UTCDateTime · required

End of the reporting period

`errors`

Type: String[]

Errors encountered during report generation

`policyDomain`

Type: String · required

Domain for which the DMARC policy is published

`policyVersion`

Type: String?

Version of the published DMARC policy

`policyAdkim`

Type: DmarcAlignment · required

DKIM alignment mode specified in the policy

`policyAspf`

Type: DmarcAlignment · required

SPF alignment mode specified in the policy

`policyDisposition`

Type: DmarcDisposition · required

Requested handling policy for failing messages

`policySubdomainDisposition`

Type: DmarcDisposition · required

Requested handling policy for failing messages from subdomains

`policyTestingMode`

Type: Boolean · default: false

Whether the policy is in testing mode (pct < 100)

`policyFailureReportingOptions`

Type: FailureReportingOption[]

Conditions under which failure reports should be generated

`records`

Type: DmarcReportRecord[]

Aggregated authentication results grouped by source

`extensions`

Type: DmarcExtension[]

Custom vendor-specific extensions to the report

DmarcReportRecord

An aggregated authentication result record from a single source.

`sourceIp`

Type: IpAddr?

IP address of the sending mail server

`count`

Type: UnsignedInt · default: 0

Number of messages from this source matching this result

`evaluatedDisposition`

Type: DmarcActionDisposition · required

Action taken on the messages

`evaluatedDkim`

Type: DmarcResult · required

DMARC result based on DKIM authentication

`evaluatedSpf`

Type: DmarcResult · required

DMARC result based on SPF authentication

`policyOverrideReasons`

Type: DmarcPolicyOverrideReason[]

Reasons why the evaluated disposition differs from the published policy

`envelopeTo`

Type: String?

Envelope recipient domain

`envelopeFrom`

Type: String · required

Envelope sender domain (MAIL FROM)

`headerFrom`

Type: String · required

Domain from the message From header

`dkimResults`

Type: DmarcDkimResult[]

DKIM authentication results for the messages

`spfResults`

Type: DmarcSpfResult[]

SPF authentication results for the messages

`extensions`

Type: DmarcExtension[]

Custom vendor-specific extensions to this record

DmarcPolicyOverrideReason

Reason for a DMARC policy override.

`overrideType`

Type: DmarcPolicyOverride · required

Type of policy override applied

`comment`

Type: String?

Additional explanation for the override

DmarcDkimResult

DKIM authentication result within a DMARC report record.

`domain`

Type: DomainName · required

Domain that signed the message

`selector`

Type: String · required

DKIM selector used for signing

`result`

Type: DkimAuthResult · required

DKIM verification result

`humanResult`

Type: String?

Human-readable explanation of the result

DmarcSpfResult

SPF authentication result within a DMARC report record.

`domain`

Type: DomainName · required

Domain checked for SPF

`scope`

Type: SpfDomainScope · required

Which identity was checked

`result`

Type: SpfAuthResult · required

SPF verification result

`humanResult`

Type: String?

Human-readable explanation of the result

DmarcExtension

A vendor-specific extension in a DMARC report.

`name`

Type: String · required

Extension identifier

`definition`

Type: String · required

Extension content or value

Enums

DmarcAlignment

Value	Label
`relaxed`	Organizational domain match is sufficient
`strict`	Exact domain match is required
`unspecified`	Alignment mode not specified

DmarcDisposition

Value	Label
`none`	No specific action requested
`quarantine`	Treat failing messages as suspicious
`reject`	Reject failing messages
`unspecified`	Disposition not specified

FailureReportingOption

Value	Label
`all`	Generate report if all authentication mechanisms fail
`any`	Generate report if any authentication mechanism fails
`dkimFailure`	Generate report if DKIM authentication fails
`spfFailure`	Generate report if SPF authentication fails

DmarcActionDisposition

Value	Label
`none`	No action taken
`pass`	Message passed evaluation
`quarantine`	Message was quarantined
`reject`	Message was rejected
`unspecified`	Disposition not specified

DmarcResult

Value	Label
`pass`	Authentication passed
`fail`	Authentication failed
`unspecified`	Result not specified

DmarcPolicyOverride

Value	Label
`Forwarded`	Message was forwarded
`SampledOut`	Message was excluded by policy sampling (pct)
`TrustedForwarder`	Message came from a trusted forwarder
`MailingList`	Message came from a mailing list
`LocalPolicy`	Local policy override was applied
`Other`	Other reason for override

DkimAuthResult

Value	Label
`none`	No DKIM signature present
`pass`	DKIM signature verified successfully
`fail`	DKIM signature verification failed
`policy`	DKIM signature not accepted due to policy
`neutral`	DKIM verification returned neutral
`tempError`	Temporary error during verification
`permError`	Permanent error in DKIM record or signature

SpfDomainScope

Value	Label
`helo`	SPF check performed on HELO/EHLO identity
`mailFrom`	SPF check performed on MAIL FROM identity
`unspecified`	Scope not specified

SpfAuthResult

Value	Label
`none`	No SPF record found
`neutral`	SPF record returned neutral
`pass`	SPF check passed
`fail`	SPF check failed (hard fail)
`softFail`	SPF check returned soft fail
`tempError`	Temporary error during SPF check
`permError`	Permanent error in SPF record