Task

Represents a background task scheduled for execution.

This object can be configured from the WebUI under Management › Tasks › Scheduled Management › Tasks › Failed

Fields

Task is a multi-variant object: each instance has an @type discriminator selecting one of the variants below, and each variant carries its own set of fields.

@type: "IndexDocument"

Index document

documentType

Type: IndexDocumentType · read-only

Type of document associated with the task

accountId

Type: Id<Account> · read-only

Identifier of the account associated with this task

documentId

Type: Id · read-only

Identifier of the document associated with this task

status

Type: TaskStatus · required

Current status of the task

due

Type: UTCDateTime? · server-set

Due date and time for the task

@type: "UnindexDocument"

Unindex document

documentType

Type: IndexDocumentType · read-only

Type of document associated with the task

accountId

Type: Id<Account> · read-only

Identifier of the account associated with this task

documentId

Type: Id · read-only

Identifier of the document associated with this task

status

Type: TaskStatus · required

Current status of the task

due

Type: UTCDateTime? · server-set

Due date and time for the task

@type: "IndexTrace"

Index telemetry trace

traceId

Type: Id<Trace> · read-only

Identifier of the trace associated with this task

status

Type: TaskStatus · required

Current status of the task

due

Type: UTCDateTime? · server-set

Due date and time for the task

@type: "CalendarAlarmEmail"

Calendar alarm e-mail

alarmId

Type: UnsignedInt · server-set · default: 0

Identifier of the calendar alarm associated with this task

eventId

Type: UnsignedInt · server-set · default: 0

Identifier of the calendar event associated with this task

eventStart

Type: UTCDateTime · server-set

Start date and time of the calendar event

eventEnd

Type: UTCDateTime · server-set

End date and time of the calendar event

eventStartTz

Type: UnsignedInt · server-set · default: 0

Timezone identifier for the start date and time

eventEndTz

Type: UnsignedInt · server-set · default: 0

Timezone identifier for the end date and time

accountId

Type: Id<Account> · read-only

Identifier of the account associated with this task

documentId

Type: Id · read-only

Identifier of the document associated with this task

status

Type: TaskStatus · required

Current status of the task

due

Type: UTCDateTime? · server-set

Due date and time for the task

@type: "CalendarAlarmNotification"

Calendar alarm notification

alarmId

Type: UnsignedInt · server-set · default: 0

Identifier of the calendar alarm associated with this task

eventId

Type: UnsignedInt · server-set · default: 0

Identifier of the calendar event associated with this task

recurrenceId

Type: Integer? · server-set

Recurrence identifier for the alarm, if applicable

accountId

Type: Id<Account> · read-only

Identifier of the account associated with this task

documentId

Type: Id · read-only

Identifier of the document associated with this task

status

Type: TaskStatus · required

Current status of the task

due

Type: UTCDateTime? · server-set

Due date and time for the task

@type: "CalendarItipMessage"

Calendar iTIP message

messages

Type: TaskCalendarItipContents[] · server-set

List of iTIP messages associated with this task

accountId

Type: Id<Account> · read-only

Identifier of the account associated with this task

documentId

Type: Id · read-only

Identifier of the document associated with this task

status

Type: TaskStatus · required

Current status of the task

due

Type: UTCDateTime? · server-set

Due date and time for the task

@type: "MergeThreads"

Merge email threads

accountId

Type: Id<Account> · server-set

Identifier of the account associated with this task

threadName

Type: String · server-set

Name of the thread to be merged

messageIds

Type: String[] · server-set

Message-IDs of the email messages to be merged into the thread

status

Type: TaskStatus · required

Current status of the task

due

Type: UTCDateTime? · server-set

Due date and time for the task

@type: "DmarcReport"

Send DMARC report to remote server

reportId

Type: Id<DmarcInternalReport> · server-set

Identifier for the DMARC aggregate report associated with this task

status

Type: TaskStatus · required

Current status of the task

due

Type: UTCDateTime? · server-set

Due date and time for the task

@type: "TlsReport"

Send TLS report to remote server

reportId

Type: Id<TlsInternalReport> · server-set

Identifier for the TLS aggregate report associated with this task

status

Type: TaskStatus · required

Current status of the task

due

Type: UTCDateTime? · server-set

Due date and time for the task

@type: "RestoreArchivedItem"

Restore archived item

blobId

Type: BlobId · server-set

Identifier of the archived blob to be restored

archivedItemType

Type: ArchivedItemType · server-set

Type of the archived item associated with the blob

createdAt

Type: UTCDateTime · server-set

Timestamp when the item was originally created

archivedUntil

Type: UTCDateTime · server-set

Timestamp until which the archived item will be deleted permanently if not restored

accountId

Type: Id<Account> · server-set

Identifier of the account to which the archived item belongs

status

Type: TaskStatus · required

Current status of the task

due

Type: UTCDateTime? · server-set

Due date and time for the task

@type: "DestroyAccount"

Destroy account and all associated data

accountId

Type: Id<Account> · server-set

Identifier of the account to be destroyed

accountName

Type: String · required

Name of the account to be destroyed

accountDomainId

Type: Id<Domain> · required

Domain identifier of the account to be destroyed, if applicable

accountType

Type: AccountType · server-set

Type of the deleted account (user or group)

status

Type: TaskStatus · required

Current status of the task

due

Type: UTCDateTime? · server-set

Due date and time for the task

@type: "AccountMaintenance"

Perform account maintenance operations

accountId

Type: Id<Account> · read-only

Identifier of the account to be maintained

maintenanceType

Type: TaskAccountMaintenanceType · read-only

Type of maintenance operation to perform on the account

status

Type: TaskStatus · required

Current status of the task

due

Type: UTCDateTime? · server-set

Due date and time for the task

@type: "TenantMaintenance"

Perform tenant maintenance operations

tenantId

Type: Id<Tenant> · read-only

Identifier of the tenant to be maintained

maintenanceType

Type: TaskTenantMaintenanceType · read-only

Type of maintenance operation to perform on the tenant

status

Type: TaskStatus · required

Current status of the task

due

Type: UTCDateTime? · server-set

Due date and time for the task

@type: "StoreMaintenance"

Perform store maintenance operations

maintenanceType

Type: TaskStoreMaintenanceType · read-only

Type of maintenance operation to perform on the store

shardIndex

Type: UnsignedInt?

Index of the shard to perform maintenance on, if applicable for the maintenance type

status

Type: TaskStatus · required

Current status of the task

due

Type: UTCDateTime? · server-set

Due date and time for the task

@type: "SpamFilterMaintenance"

Perform spam filter maintenance operations

maintenanceType

Type: TaskSpamFilterMaintenanceType · read-only

Type of maintenance operation to perform on the spam filter

status

Type: TaskStatus · required

Current status of the task

due

Type: UTCDateTime? · server-set

Due date and time for the task

@type: "AcmeRenewal"

Perform ACME certificate renewal for a domain

domainId

Type: Id<Domain> · read-only

Identifier of the domain associated with this task

status

Type: TaskStatus · required

Current status of the task

due

Type: UTCDateTime? · server-set

Due date and time for the task

@type: "DkimManagement"

Perform DKIM key rotation for a domain

domainId

Type: Id<Domain> · read-only

Identifier of the domain associated with this task

status

Type: TaskStatus · required

Current status of the task

due

Type: UTCDateTime? · server-set

Due date and time for the task

@type: "DnsManagement"

Perform DNS management for a domain

updateRecords

Type: DnsRecordType[]

Which DNS records should be updated for the domain as part of this task

onSuccessRenewCertificate

Type: Boolean · default: false

Whether to automatically renew the domain's TLS certificate using ACME after successfully updating DNS records

domainId

Type: Id<Domain> · read-only

Identifier of the domain associated with this task

status

Type: TaskStatus · required

Current status of the task

due

Type: UTCDateTime? · server-set

Due date and time for the task

JMAP API

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

x:Task/get

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

This method requires the sysTaskGet permission.

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

x:Task/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 sysTaskCreate permission.

curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:Task/set",
          {
            "create": {
              "new1": {
                "@type": "IndexDocument",
                "status": {
                  "@type": "Pending",
                  "due": "2026-01-01T00:00:00Z"
                }
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

Update

This operation requires the sysTaskUpdate permission.

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

Destroy

This operation requires the sysTaskDestroy permission.

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

x:Task/query

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

This method requires the sysTaskQuery permission.

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

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

Condition	Kind
@type	enum: TaskType
status	enum: TaskStatusType
due	date

CLI

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

Fetch

stalwart-cli get task id1

Create

stalwart-cli create task/index-document \
  --field 'status={"@type":"Pending","due":"2026-01-01T00:00:00Z"}'

Query

stalwart-cli query task
stalwart-cli query task --where @type=value

Update

stalwart-cli update task id1 --field description='Updated'

Delete

stalwart-cli delete task --ids id1

Nested types

TaskStatus

Execution status of a background task.

• Pending: Pending task awaiting execution. Carries the fields of TaskStatusPending.
• Retry: Task scheduled for retry. Carries the fields of TaskStatusRetry.
• Failed: Failed task. Carries the fields of TaskStatusFailed.

TaskStatusPending

Pending task status details.

createdAt

Type: UTCDateTime · server-set

Date and time when the task was created

due

Type: UTCDateTime · required

Due date and time for the task

TaskStatusRetry

Task retry status details.

createdAt

Type: UTCDateTime · server-set

Date and time when the task was created

due

Type: UTCDateTime · required

Due date and time for the task

attemptNumber

Type: UnsignedInt · default: 1

Number of attempts made to complete the task

failureReason

Type: Text · required

Reason for the last failure

TaskStatusFailed

Failed task status details.

createdAt

Type: UTCDateTime · server-set

Date and time when the task was created

failedAt

Type: UTCDateTime · required

Date and time when the task failed

failedAttemptNumber

Type: UnsignedInt · default: 0

Number of attempts made before the task failed

failureReason

Type: Text · required

Reason for task failure

TaskCalendarItipContents

Contents of an iTIP message to be delivered.

from

Type: EmailAddress · server-set

Email address of the sender of the iTIP message

to

Type: EmailAddress[] · server-set

Email addresses of the recipients of the iTIP message

isFromOrganizer

Type: Boolean · server-set · default: false

Indicates whether the sender is the organizer of the calendar event

iCalendarData

Type: String · server-set

iCalendar data associated with the iTIP message

summary

Type: String · server-set

Summary of the calendar event associated with the iTIP message

Enums

IndexDocumentType

Value	Label
email	Email
calendar	Calendar
contacts	Contacts
file	File

ArchivedItemType

Value	Label
Email	Archived Email message
FileNode	Archived File
CalendarEvent	Archived Calendar Event
ContactCard	Archived Contact Card
SieveScript	Archived Sieve Script

AccountType

Value	Label
User	User account
Group	Group account

TaskAccountMaintenanceType

Value	Label
purge	Purge expired data from the account
reindex	Reindex the account's data for search
recalculateImapUid	Recalculate IMAP UIDs for the account's email messages
recalculateQuota	Recalculate storage quota usage for the account

TaskTenantMaintenanceType

Value	Label
recalculateQuota	Recalculate storage quota usage for the tenant

TaskStoreMaintenanceType

Value	Label
reindexAccounts	Reindex all accounts' data for search
reindexTelemetry	Reindex all telemetry data for search
purgeAccounts	Purge expired data from all accounts
purgeData	Purge data store
purgeBlob	Purge blob store
resetRateLimiters	Reset all rate limiters
resetUserQuotas	Reset all user quotas
resetTenantQuotas	Reset all tenant quotas
resetBlobQuotas	Reset all blob quotas
removeAuthTokens	Delete all temporary ACME and OAuth tokens
removeLockQueueMessage	Delete all MTA queue message locks
removeLockTask	Delete all task manager locks
removeLockDav	Delete all DAV locks
removeSieveId	Delete all Sieve vacation and duplicate ID lists
removeGreylist	Delete all spam filter grey list entries

TaskSpamFilterMaintenanceType

Value	Label
train	Train the spam classifier with the latest samples
retrain	Retrain the spam classifier with all available samples
abort	Abort the ongoing training process of the spam classifier
reset	Delete the spam classifier's model and reset it to the default state
updateRules	Download and update the spam filter rules from the configured source

DnsRecordType

Value	Label
dkim	DKIM public keys
tlsa	TLSA records
spf	SPF records
mx	MX records
dmarc	DMARC policy
srv	SRV records
mtaSts	MTA-STS policy record
tlsRpt	TLS reporting record
caa	CAA records
autoConfig	Autoconfig records
autoConfigLegacy	Legacy Autoconfig records
autoDiscover	Microsoft Autodiscover records