Skip to main content
Version: 0.16

ArfExternalReport

Stores an ARF feedback report received from an external source.

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

Fields​

report​

Type: ArfFeedbackReport · required

Parsed ARF feedback 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 ArfExternalReport object is available via the urn:stalwart:jmap capability.

x:ArfExternalReport/get​

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

This method requires the sysArfExternalReportGet permission.

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

x:ArfExternalReport/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 sysArfExternalReportCreate permission.

curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:ArfExternalReport/set",
          {
            "create": {
              "new1": {
                "expiresAt": "2026-01-01T00:00:00Z",
                "from": "[email protected]",
                "memberTenantId": "<Tenant id>",
                "receivedAt": "2026-01-01T00:00:00Z",
                "report": {
                  "arrivalDate": "2026-01-01T00:00:00Z",
                  "authFailure": "adsp",
                  "authenticationResults": [],
                  "deliveryResult": "delivered",
                  "dkimAdspDns": "Example",
                  "dkimCanonicalizedBody": "Example",
                  "dkimCanonicalizedHeader": "Example",
                  "dkimDomain": "Example",
                  "dkimIdentity": "Example",
                  "dkimSelector": "Example",
                  "dkimSelectorDns": "Example",
                  "feedbackType": "abuse",
                  "headers": "Example",
                  "identityAlignment": "none",
                  "incidents": 0,
                  "message": "Example",
                  "originalEnvelopeId": "Example",
                  "originalMailFrom": "[email protected]",
                  "originalRcptTo": "[email protected]",
                  "reportedDomains": [],
                  "reportedUris": [],
                  "reportingMta": "Example",
                  "sourceIp": "192.0.2.1",
                  "sourcePort": 1000,
                  "spfDns": "Example",
                  "userAgent": "Example",
                  "version": 1
                },
                "subject": "Example",
                "to": []
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

Update​

This operation requires the sysArfExternalReportUpdate permission.

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

Destroy​

This operation requires the sysArfExternalReportDestroy permission.

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

x:ArfExternalReport/query​

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

This method requires the sysArfExternalReportQuery permission.

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

Create​

stalwart-cli create arf-external-report \
  --field 'report={"arrivalDate":"2026-01-01T00:00:00Z","authFailure":"adsp","authenticationResults":[],"deliveryResult":"delivered","dkimAdspDns":"Example","dkimCanonicalizedBody":"Example","dkimCanonicalizedHeader":"Example","dkimDomain":"Example","dkimIdentity":"Example","dkimSelector":"Example","dkimSelectorDns":"Example","feedbackType":"abuse","headers":"Example","identityAlignment":"none","incidents":0,"message":"Example","originalEnvelopeId":"Example","originalMailFrom":"[email protected]","originalRcptTo":"[email protected]","reportedDomains":[],"reportedUris":[],"reportingMta":"Example","sourceIp":"192.0.2.1","sourcePort":1000,"spfDns":"Example","userAgent":"Example","version":1}' \
  --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 arf-external-report

Update​

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

Delete​

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

Nested types​

ArfFeedbackReport​

Parsed content of an ARF feedback report.

feedbackType​

Type: ArfFeedbackType · required

Type of feedback being reported

arrivalDate​

Type: UTCDateTime?

When the original message arrived

authenticationResults​

Type: String[]

Authentication-Results header values from the original message

incidents​

Type: UnsignedInt · default: 0

Number of incidents represented by this report

originalEnvelopeId​

Type: String?

Original SMTP envelope ID (ENVID)

originalMailFrom​

Type: EmailAddress?

Original envelope sender address (MAIL FROM)

originalRcptTo​

Type: EmailAddress?

Original envelope recipient address (RCPT TO)

reportedDomains​

Type: DomainName[]

Domains being reported

reportedUris​

Type: Uri[]

URIs being reported

reportingMta​

Type: String?

Hostname of the MTA generating this report

sourceIp​

Type: IpAddr?

IP address of the original message source

sourcePort​

Type: UnsignedInt? · min: 1 · max: 65535

Port of the original message source

userAgent​

Type: String?

Software that generated this report

version​

Type: UnsignedInt · default: 1

ARF format version

authFailure​

Type: ArfAuthFailureType · required

Type of authentication failure (for auth-failure reports)

deliveryResult​

Type: ArfDeliveryResult · required

What happened to the original message

dkimAdspDns​

Type: String?

DKIM ADSP DNS record content

dkimCanonicalizedBody​

Type: String?

Message body after DKIM canonicalization

dkimCanonicalizedHeader​

Type: String?

Message headers after DKIM canonicalization

dkimDomain​

Type: String?

Domain from the DKIM signature

dkimIdentity​

Type: String?

Identity from the DKIM signature (i= tag)

dkimSelector​

Type: String?

Selector from the DKIM signature

dkimSelectorDns​

Type: String?

DKIM selector DNS record content

spfDns​

Type: String?

SPF DNS record content

identityAlignment​

Type: ArfIdentityAlignment · required

Which identities were aligned

message​

Type: String?

Original message content that triggered the report

headers​

Type: String?

Original message headers that triggered the report

Enums​

ArfFeedbackType​

ValueLabel
abuseMessage was reported as abusive or unwanted
authFailureMessage failed authentication checks
fraudMessage was reported as fraudulent
notSpamMessage was incorrectly classified as spam
virusMessage contained a virus
otherOther feedback type

ArfAuthFailureType​

ValueLabel
adspDKIM ADSP policy failure
bodyHashDKIM body hash verification failed
revokedDKIM key has been revoked
signatureDKIM signature verification failed
spfSPF authentication failed
dmarcDMARC authentication failed
unspecifiedAuthentication failure type not specified

ArfDeliveryResult​

ValueLabel
deliveredMessage was delivered to recipient
spamMessage was delivered to spam folder
policyMessage was handled according to policy
rejectMessage was rejected
otherOther delivery result
unspecifiedDelivery result not specified

ArfIdentityAlignment​

ValueLabel
noneNo identity alignment
spfSPF identity aligned
dkimDKIM identity aligned
dkimSpfBoth DKIM and SPF identities aligned
unspecifiedIdentity alignment not specified