Queue and report management

While the MTA runs, it keeps two kinds of records that administrators need to inspect and act on. The first is the queue: the messages that are waiting to be delivered. The second is the set of reports that Stalwart exchanges with other mail servers about authentication and TLS. An administrator looks at the queue to find out why a message has not arrived or to retry it after a fault is fixed, and at the reports to learn how other servers see the local domains.

The server creates both kinds of record itself as mail flows, and an administrator cannot create them. They are managed through the WebUI, the CLI or the JMAP API. Each kind of record allows only the operations that make sense for it:

Object	List and view	Create	Update	Delete
QueuedMessage	Yes	No	Yes: reschedule, cancel recipients	Yes
DmarcInternalReport, TlsInternalReport	Yes	No	Yes	Yes
DmarcExternalReport, TlsExternalReport, ArfExternalReport	Yes	No	No	Yes

Queued messages

Each message in the queue is a QueuedMessage (found in the WebUI under Management › Emails › Queued). The object shows the envelope sender of the message, its size and its priority. For each recipient, it also shows the delivery state:

• The virtual queue the recipient is in
• The delivery status and the number of attempts made
• The time of the next attempt, of the next delay notification and of the expiry
• The error returned by the last attempt

Messages can be searched by text, by recipient, by queue, by sender or by due time. The following commands list the queued messages for a recipient and then show one of them:

stalwart-cli query QueuedMessage --where [email protected]
stalwart-cli get QueuedMessage <id>

Rescheduling delivery

After a problem on the remote server has been fixed, there is no need to wait for the next scheduled attempt: the message can be retried at once. Setting nextRetry to a time reschedules every recipient of the message that has not failed permanently. The following command sets the next attempt to a given time, which in this case is the present moment:

stalwart-cli update QueuedMessage <id> --field nextRetry=2026-10-15T12:00:00Z

To reschedule a single recipient instead of the whole message, use the field recipients/<address>/retryDue in place of nextRetry.

A recipient that has failed permanently is not affected by nextRetry. Retrying it takes two steps. First, set its status back to scheduled with --field 'recipients/<address>/status={"@type":"Scheduled"}'. Then reschedule it in a separate update.

Cancelling delivery

Delivery can be cancelled for one recipient or for the whole message. Removing a recipient from the message with --field 'recipients/<address>=null' cancels its delivery, and the cancellation is recorded as Delivery canceled. Once no recipient is left to deliver, the message itself is removed. To remove the message with all its recipients at once, delete the QueuedMessage:

stalwart-cli delete QueuedMessage --ids <id>

Pausing the queue

Sometimes deliveries must stop for a while without refusing new mail. The PauseMtaQueue and ResumeMtaQueue actions stop and restart the delivery of queued messages, and they act on every node of the cluster. While the queue is paused, Stalwart still accepts messages and queues them, but it delivers nothing until the queue is resumed. Pausing is useful during maintenance of a relay or of the network. It is also useful to examine the queue while no delivery is changing it:

stalwart-cli create Action/PauseMtaQueue
stalwart-cli create Action/ResumeMtaQueue

Received reports

Other organisations send reports about the mail they receive from the local domains. Stalwart keeps these reports for review for the period set by holdMtaReportsFor on the DataRetention singleton, which is 30 days unless changed. When the field is not set, received reports are not kept. Three kinds of report are stored:

• DmarcExternalReport (found in the WebUI under Management › Reports › Inbox › DMARC): DMARC aggregate reports. Each summarises how a receiver evaluated SPF, DKIM and DMARC for the messages that claimed to come from a local domain.
• TlsExternalReport (found in the WebUI under Management › Reports › Inbox › TLS): TLS reports. Each describes whether other servers could establish TLS when they delivered mail to the local domains.
• ArfExternalReport (found in the WebUI under Management › Reports › Inbox › ARF): feedback reports in the Abuse Reporting Format, such as abuse complaints and authentication failure reports.

These reports are records of what other servers observed, so they cannot be modified. They can only be viewed and deleted. Report analysis describes how Stalwart recognises and stores them.

Outgoing reports

Stalwart also sends DMARC and TLS reports to other domains, and these reports are built up over a reporting period. While a period is open, Stalwart keeps the results it collects as counters, which are not listed anywhere. About five minutes after the period ends, a DmarcReportWindow or TlsReportWindow task turns the counters into one report object per destination domain. Each report is kept until it is sent, which happens between five and fifteen minutes after the end of the period. Two kinds of pending report exist:

• DmarcInternalReport (found in the WebUI under Management › Reports › Outbox › DMARC): DMARC aggregate reports for the domains whose DMARC record requests them.
• TlsInternalReport (found in the WebUI under Management › Reports › Outbox › TLS): TLS reports for the domains that publish a TLS reporting record.

Deleting a pending report discards it, so the report is never sent. DMARC reports and TLS reports describe how the reports are produced and sent.