Skip to main content
Version: 0.16

Trace

Stores a message delivery trace with associated events.

Enterprise feature

This object is only available with an Enterprise license.

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):

ConditionKind
texttext
timestampdate
queueIdtext

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 description='Updated'

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.

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