Trace

Stores a message delivery trace with associated events.

This object can be configured from the WebUI under Management › Emails › History › Inbound Delivery Management › Emails › History › Outbound Delivery

Fields

`events`

Type: TraceEvent[]

List of events associated with the trace entry

`timestamp`

Type: UTCDateTime · server-set

Timestamp of the trace entry

`from`

Type: String · server-set

Sender address

`to`

Type: String · server-set

Recipient addresses

`size`

Type: Size · server-set

Size of the message

JMAP API

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

`x:Trace/get`

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

This method requires the sysTraceGet permission.

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

`x:Trace/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 sysTraceCreate permission.

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

Update

This operation requires the sysTraceUpdate permission.

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

Destroy

This operation requires the sysTraceDestroy permission.

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

`x:Trace/query`

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

This method requires the sysTraceQuery permission.

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

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

Condition	Kind
`text`	text
`timestamp`	date
`queueId`	text

CLI

stalwart-cli wraps the same JMAP calls. See the CLI reference for installation, authentication, and general usage.

Fetch

stalwart-cli get Trace id1

Create

stalwart-cli create Trace \
  --field 'events={}'

Query

stalwart-cli query Trace

Update

stalwart-cli update Trace id1 --field events='{}'

Delete

stalwart-cli delete Trace --ids id1

Nested types

TraceEvent

A single event within a delivery trace.

`event`

Type: EventType · required

Event type

`timestamp`

Type: UTCDateTime · required

Timestamp when the event occurred

`keyValues`

Type: TraceKeyValue[]

List of key-value pairs associated with the trace entry

TraceKeyValue

A key-value pair associated with a trace event.

`key`

Type: Key · required

Key name

`value`

Type: TraceValue · required

Key value

TraceValue

A typed value in a trace key-value pair.

String: String value. Carries the fields of TraceValueString.
UnsignedInt: Unsigned integer value. Carries the fields of TraceValueUnsignedInt.
Integer: Integer value. Carries the fields of TraceValueInteger.
Boolean: Boolean value. Carries the fields of TraceValueBoolean.
Float: Float value. Carries the fields of TraceValueFloat.
UTCDateTime: UTC date and time value. Carries the fields of TraceValueUTCDateTime.
Duration: Duration value in seconds. Carries the fields of TraceValueDuration.
IpAddr: IP address value. Carries the fields of TraceValueIpAddr.
List: Value list. Carries the fields of TraceValueList.
Event: Nested event value. Carries the fields of TraceValueEvent.
Null: Null value. No additional fields.

TraceValueString

A string trace value.

`value`

Type: String · required

String value

TraceValueUnsignedInt

An unsigned integer trace value.

`value`

Type: UnsignedInt · default: 0

Unsigned integer value

TraceValueInteger

An integer trace value.

`value`

Type: Integer · default: 0

Integer value

TraceValueBoolean

A boolean trace value.

`value`

Type: Boolean · default: false

Boolean value

TraceValueFloat

A floating-point trace value.

`value`

Type: Float · default: 0

Float value

TraceValueUTCDateTime

A UTC date-time trace value.

`value`

Type: UTCDateTime · required

UTC date and time value

TraceValueDuration

A duration trace value in seconds.

`value`

Type: UnsignedInt · default: 0

Duration value in seconds

TraceValueIpAddr

An IP address trace value.

`value`

Type: IpAddr · required

IP address value

TraceValueList

A list of trace values.

`value`

Type: TraceValue[]

Value list

TraceValueEvent

A nested event trace value.

`event`

Type: EventType · required

Event type

`value`

Type: TraceKeyValue[]

List of key-value pairs associated with the trace entry