Skip to main content
Version: 0.16

Tasks

A Task is a background job scheduled for execution. Tasks cover the recurring or deferred work the server performs outside the request path: search indexing, calendar alarm dispatch, outbound DMARC and TLS reports, account destruction, store and spam filter maintenance, ACME renewal, DKIM key rotation, and DNS record updates. Each scheduled job is represented as a Task object (found in the WebUI under Management › Tasks › Scheduled, Management › Tasks › Failed) of one of the variants described below, and whose status records whether the task is pending, awaiting retry, or has failed permanently.

Tasks are visible and manageable from the WebUI (Management › Tasks › Scheduled and Management › Tasks › Failed), through the CLI using stalwart-cli get task, stalwart-cli query task, and stalwart-cli create task/<variant-name>, and over the JMAP API through the x:Task/get, x:Task/query, and x:Task/set methods. Administrators can reschedule, retry, or destroy individual tasks through the same interfaces.

Variants​

Every variant of the Task object carries a status and a due timestamp; variants specific to an account, domain, or other object carry the corresponding identifier. The full schema for each is on the reference page.

Index document​

The IndexDocument variant indexes a single document for search. The caller supplies the owning accountId, the documentId, and the documentType, which selects between email, calendar, contacts, and file.

Unindex document​

The UnindexDocument variant removes a single document from the search index. The caller supplies the owning accountId, the documentId, and the documentType matching the previously indexed document.

Index trace​

The IndexTrace variant indexes a telemetry trace so that it becomes queryable. The caller supplies the traceId of the trace to index.

Calendar alarm email​

The CalendarAlarmEmail variant sends the email notification for a calendar alarm at the scheduled time. The server populates the alarm and event identifiers together with the event start and end timestamps and their timezone identifiers, and records the owning accountId and documentId of the calendar event.

Calendar alarm notification​

The CalendarAlarmNotification variant delivers the in-app notification for a calendar alarm at the scheduled time. Alongside the alarm and event identifiers, the server records an optional recurrenceId when the alarm targets a specific occurrence of a recurring event.

Calendar iTIP message​

The CalendarItipMessage variant delivers one or more iTIP messages for a calendar event to their recipients. The server populates messages with the per-recipient iTIP payloads together with the owning accountId and documentId.

Merge threads​

The MergeThreads variant merges email messages that share a thread identifier into a single thread. The server records the owning accountId, the threadName, and the list of messageIds to fold into the thread.

DMARC report​

The DmarcReport variant submits a DMARC aggregate report to the remote reporting address for a reporting window. The task carries the reportId of the internal report object holding the aggregated data.

TLS report​

The TlsReport variant submits a TLS aggregate report to the remote reporting address for a reporting window. The task carries the reportId of the internal TLS report object holding the aggregated data.

Restore archived item​

The RestoreArchivedItem variant restores an archived item into the owning account before its archive retention expires. The task carries the blobId of the archived payload, the archivedItemType (email, file, calendar event, contact card, or Sieve script), the original createdAt timestamp, the archivedUntil deadline after which the item is deleted permanently, and the destination accountId.

Destroy account​

The DestroyAccount variant permanently deletes an account and all data associated with it. The caller supplies the accountName and accountDomainId; the server records the resolved accountId and accountType, either user or group.

Account maintenance​

The AccountMaintenance variant runs a per-account maintenance operation selected by maintenanceType: purging expired data, reindexing for search, recalculating IMAP UIDs, or recalculating storage quota usage. The task carries the owning accountId.

Tenant maintenance​

The TenantMaintenance variant runs a per-tenant maintenance operation selected by maintenanceType; currently, the only operation is recalculating tenant-wide storage quota usage. The task carries the owning tenantId.

Store maintenance​

The StoreMaintenance variant runs a store-wide maintenance operation selected by maintenanceType: reindexing all accounts or telemetry data, purging the data or blob stores, resetting user, tenant, or blob quotas, resetting rate limiters, or removing stale ACME and OAuth tokens, MTA queue locks, task manager locks, DAV locks, Sieve vacation and duplicate ID lists, or greylist entries. For sharded stores, an optional shardIndex selects the target shard.

Spam filter maintenance​

The SpamFilterMaintenance variant operates on the spam classifier according to maintenanceType: training on the latest samples, retraining on all available samples, aborting an ongoing training run, resetting the classifier model to its default state, or downloading and applying rule updates from the configured source.

ACME renewal​

The AcmeRenewal variant renews the ACME-issued TLS certificate for a domain. The task carries the target domainId.

DKIM rotation​

The DkimManagement variant performs DKIM key rotation for a domain. The task carries the target domainId.

DNS record update​

The DnsManagement variant updates one or more DNS record types for a domain. The updateRecords field selects from DKIM public keys, TLSA, SPF, MX, DMARC, SRV, MTA-STS, TLS-RPT, CAA, Autoconfig (including the legacy variant), and Microsoft Autodiscover records, and onSuccessRenewCertificate optionally triggers an ACME renewal after a successful update. The task carries the target domainId.

Retry status​

Every task carries a status field drawn from the TaskStatus nested type. A task awaiting its first execution is Pending and carries a due timestamp. A task that has failed but is still within its retry budget becomes Retry and records the attemptNumber and the failureReason from the last attempt. A task that has exhausted its retry budget becomes Failed and records the failedAt timestamp, the failedAttemptNumber, and the terminal failureReason.

Task Manager​

Global settings controlling how tasks are retried are held on the TaskManager singleton (found in the WebUI under Settings › Task Manager). The relevant fields are:

  • maxAttempts: maximum number of attempts for a task before it is marked as permanently failed. Default 3, minimum 1.
  • strategy: retry strategy applied to failed tasks. Either the ExponentialBackoff variant, configured with a factor, an initialDelay, a maxDelay, and an optional jitter toggle, or the FixedDelay variant, configured with a single delay.
  • totalDeadline: total time budget across all attempts before a task is marked as failed regardless of remaining attempts. Default "6h".

Example using exponential backoff with jitter:

{
  "maxAttempts": 5,
  "strategy": {
    "@type": "ExponentialBackoff",
    "factor": 2.0,
    "initialDelay": "1m",
    "maxDelay": "30m",
    "jitter": true
  },
  "totalDeadline": "6h"
}

TaskManager settings are read through x:TaskManager/get with id singleton and updated through x:TaskManager/set (only the update argument is accepted). The CLI equivalents are stalwart-cli get task-manager and stalwart-cli update task-manager. Access is gated by the sysTaskManagerGet and sysTaskManagerUpdate permissions.