Skip to main content
Version: 0.16

DataRetention

Configures data retention policies, expunge schedules, and archival settings.

This object can be configured from the WebUI under Settings › Storage › Data Retention › Archiving Settings › Storage › Data Retention › Data Cleanup Settings › Storage › Data Retention › Auto-Expunge Settings › Storage › Data Retention › Telemetry

Fields​

expungeTrashAfter​

Type: Duration? · default: "30d"

How long to keep messages in the Trash and Junk Mail folders before auto-expunging

expungeSubmissionsAfter​

Type: Duration? · default: "3d"

How long to keep sent e-mail submissions before auto-expunging

expungeShareNotifyAfter​

Type: Duration? · default: "30d"

Specifies the duration for which the JMAP share notification history is retained before it is automatically purged.

expungeSchedulingInboxAfter​

Type: Duration? · default: "30d"

Sets the duration after which the iTIP inbox will automatically expunge old messages.

expungeSchedule​

Type: Cron · default: {"@type":"Daily","hour":0,"minute":0}

Specifies when to run the auto-expunge process

dataCleanupSchedule​

Type: Cron · default: {"@type":"Daily","hour":2,"minute":0}

How often to purge the data store. Expects a cron expression.

blobCleanupSchedule​

Type: Cron · default: {"@type":"Daily","hour":4,"minute":0}

How often to purge the data store. Expects a cron expression.

maxChangesHistory​

Type: UnsignedInt? · default: 10000

How many changes to keep in the history for each account. This is used to determine the changes that have occurred since the last time the client requested changes.

archiveDeletedItemsFor​

Type: Duration? · enterprise

How long to keep deleted items in the archive before they are permanently deleted. If null, deleted items will not be archived and will be permanently deleted immediately.

archiveDeletedAccountsFor​

Type: Duration? · enterprise

How long to keep deleted accounts in the archive before they are permanently deleted. If null, deleted accounts will be permanently deleted immediately.

holdMtaReportsFor​

Type: Duration? · default: "30d"

The duration for which MTA reports should be stored before being deleted, or None to disable storage

holdTracesFor​

Type: Duration? · enterprise · default: "30d"

How long to keep message delivery history before it is permanently deleted.

holdMetricsFor​

Type: Duration? · enterprise · default: "90d"

How long to keep metrics history before it is permanently deleted.

metricsCollectionInterval​

Type: Cron · enterprise · default: {"@type":"Hourly","minute":0}

Specifies how often to collect metrics history.

JMAP API​

The DataRetention singleton is available via the urn:stalwart:jmap capability.

x:DataRetention/get​

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

For singletons, the ids argument should be the literal singleton (or null to return the single instance).

This method requires the sysDataRetentionGet permission.

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

x:DataRetention/set​

This is a standard Foo/set method as defined in RFC 8620, Section 5.3.

For singletons, only the update argument with id singleton is accepted; create and destroy arguments are rejected.

This method requires the sysDataRetentionUpdate permission.

curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:DataRetention/set",
          {
            "update": {
              "singleton": {
                "expungeTrashAfter": "30d"
              }
            }
          },
          "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 data-retention

Update​

stalwart-cli update data-retention --field description='Updated'

Nested types​

Cron​

Defines a recurring schedule.

  • Daily: Every day. Carries the fields of CronDaily.
  • Weekly: Every week. Carries the fields of CronWeekly.
  • Hourly: Every hour. Carries the fields of CronHourly.

CronDaily​

A daily recurring schedule at a specific time.

hour​

Type: UnsignedInt · default: 0 · max: 23

Hour

minute​

Type: UnsignedInt · default: 0 · max: 59

Minute

CronWeekly​

A weekly recurring schedule on a specific day and time.

day​

Type: UnsignedInt · default: 0 · max: 6

Day

hour​

Type: UnsignedInt · default: 0 · max: 23

Hour

minute​

Type: UnsignedInt · default: 0 · max: 59

Minute

CronHourly​

An hourly recurring schedule at a specific minute.

minute​

Type: UnsignedInt · default: 0 · max: 59

Minute