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]",
                "memberTenantId": "<Tenant id>",
                "receivedAt": "2026-01-01T00:00:00Z",
                "report": {
                  "dateRangeBegin": "2026-01-01T00:00:00Z",
                  "dateRangeEnd": "2026-01-01T00:00:00Z",
                  "email": "[email protected]",
                  "errors": [],
                  "extensions": [],
                  "extraContactInfo": "Example",
                  "orgName": "Example",
                  "policyAdkim": "relaxed",
                  "policyAspf": "relaxed",
                  "policyDisposition": "none",
                  "policyDomain": "Example",
                  "policyFailureReportingOptions": [],
                  "policySubdomainDisposition": "none",
                  "policyTestingMode": false,
                  "policyVersion": "Example",
                  "records": [],
                  "reportId": "Example",
                  "version": 1.0
                },
                "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 dmarc-external-report id1

Create

stalwart-cli create dmarc-external-report \
  --field 'report={"dateRangeBegin":"2026-01-01T00:00:00Z","dateRangeEnd":"2026-01-01T00:00:00Z","email":"[email protected]","errors":[],"extensions":[],"extraContactInfo":"Example","orgName":"Example","policyAdkim":"relaxed","policyAspf":"relaxed","policyDisposition":"none","policyDomain":"Example","policyFailureReportingOptions":[],"policySubdomainDisposition":"none","policyTestingMode":false,"policyVersion":"Example","records":[],"reportId":"Example","version":1.0}' \
  --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 dmarc-external-report
stalwart-cli query dmarc-external-report --where domain=example

Update

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

Delete

stalwart-cli delete dmarc-external-report --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