Queue
Overview
The message queue is managed using the queue CLI command which accepts the following arguments:
$ stalwart-cli -u https://mx.foobar.org:8686 -c secret queue
Manage SMTP message queue
Usage: stalwart-cli --url <URL> queue <COMMAND>
Commands:
list Shows messages queued for delivery
status Displays details about a queued message
retry Reschedule delivery
cancel Cancel delivery
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
List
The command queue list displays the messages awaiting to be delivered. It accepts the following filtering parameters:
$ stalwart-cli -u https://mx.foobar.org:8686 -c secret queue list --help
Shows messages queued for delivery
Usage: stalwart-cli queue list [OPTIONS]
Options:
-s, --sender <SENDER> Filter by sender address
-r, --rcpt <RCPT> Filter by recipient
-b, --before <BEFORE> Filter messages due for delivery before a certain datetime
-a, --after <AFTER> Filter messages due for delivery after a certain datetime
-p, --page-size <PAGE_SIZE> Number of items to show per page
-h, --help Print help
For example:
$ stalwart-cli -u https://mx.foobar.org:8686 -c secret queue list
+-----------+--------------------------------+------------------+--------------------------------+--------+
| ID | Delivery Due | Sender | Recipients | Size |
+-----------+--------------------------------+------------------+--------------------------------+--------+
| 32B91F716 | Wed, 1 Mar 2023 11:51:01 +0000 | [email protected] | [email protected] (scheduled) | 1142 B |
+-----------+--------------------------------+------------------+--------------------------------+--------+
| 22B91F716 | Wed, 1 Mar 2023 11:49:21 +0000 | [email protected] | [email protected] (scheduled) | 1142 B |
| | | | [email protected] (scheduled) | |
| | | | [email protected] (scheduled) | |
| | | | [email protected] (scheduled) | |
| | | | [email protected] (scheduled) | |
+-----------+--------------------------------+------------------+--------------------------------+--------+
| 12B91F716 | Wed, 1 Mar 2023 11:47:41 +0000 | [email protected] | [email protected] (scheduled) | 1142 B |
| | | | [email protected] (scheduled) | |
+-----------+--------------------------------+------------------+--------------------------------+--------+
| 2B91F716 | Wed, 1 Mar 2023 11:46:01 +0000 | [email protected] | [email protected] (scheduled) | 1141 B |
| | | | [email protected] (scheduled) | |
+-----------+--------------------------------+------------------+--------------------------------+--------+
| 52B91F716 | Wed, 1 Mar 2023 12:01:01 +0000 | <> | [email protected] (tempfail) | 1127 B |
| | | | [email protected] (delivered) | |
+-----------+--------------------------------+------------------+--------------------------------+--------+
| 42B91F716 | Wed, 1 Mar 2023 11:52:41 +0000 | [email protected] | [email protected] (scheduled) | 1142 B |
+-----------+--------------------------------+------------------+--------------------------------+--------+
6 queued message(s) found.
Status
The queue status command shows the details for a queued message. It accepts as parameters one or more message ids, for example:
$ stalwart-cli -u https://mx.foobar.org:8686 -c secret queue status 52B91F716
+--------------+---------------------------------------------------------------------------------------------------------+
| ID | 52B91F716 |
+--------------+---------------------------------------------------------------------------------------------------------+
| Sender | <> |
+--------------+---------------------------------------------------------------------------------------------------------+
| Created | Wed, 1 Mar 2023 11:44:22 +0000 |
+--------------+---------------------------------------------------------------------------------------------------------+
| Size | 1127 B |
+--------------+---------------------------------------------------------------------------------------------------------+
| Env-Id | f |
+--------------+---------------------------------------------------------------------------------------------------------+
| foobar.org |
+--------------+---------------------------------------------------------------------------------------------------------+
| Status | Scheduled |
+--------------+---------------------------------------------------------------------------------------------------------+
| Details | |
+--------------+---------------------------------------------------------------------------------------------------------+
| Retry # | 1 |
+--------------+---------------------------------------------------------------------------------------------------------+
| Delivery Due | Wed, 1 Mar 2023 12:01:01 +0000 |
+--------------+---------------------------------------------------------------------------------------------------------+
| Notify at | Wed, 1 Mar 2023 12:17:41 +0000 |
+--------------+---------------------------------------------------------------------------------------------------------+
| Expires | Wed, 1 Mar 2023 12:34:21 +0000 |
+--------------+---------------------------------------------------------------------------------------------------------+
| Recipients | +--------------------+-------------------+------------------------------------------------------------+ |
| | | Address | Status | Details | |
| | +--------------------+-------------------+------------------------------------------------------------+ |
| | | [email protected] | Temporary Failure | Code: 451, Enhanced code: 4.5.3, Message: Try again later. | |
| | +--------------------+-------------------+------------------------------------------------------------+ |
| | | [email protected] | Delivered | Code: 250, Enhanced code: 2.1.5, Message: OK | |
| | +--------------------+-------------------+------------------------------------------------------------+ |
+--------------+---------------------------------------------------------------------------------------------------------+
Reschedule
The queue retry commands retries or reschedules the delivery of one or multiple messages. It accepts the following parameters where BEFORE, AFTER and TIME are RFC3339 timestamps:
$ stalwart-cli -u https://mx.foobar.org:8686 -c secret queue retry --help
Reschedule delivery
Usage: stalwart-cli queue retry [OPTIONS] [IDS]...
Arguments:
[IDS]...
Options:
-s, --sender <SENDER> Apply to messages matching a sender address
-d, --domain <DOMAIN> Apply to a specific domain
-b, --before <BEFORE> Apply to messages due before a certain datetime
-a, --after <AFTER> Apply to messages due after a certain datetime
-t, --time <TIME> Schedule delivery at a specific time
-h, --help Print help
If the -t parameter is not provided, delivery is retried immediately.
Rescheduling can be done by providing a list of message ids:
$ stalwart-cli -u https://mx.foobar.org:8686 -c secret queue retry 52B91F716
Successfully rescheduled 1 message(s).
Or by using a filter that reschedules all matching messages:
$ stalwart-cli -u https://mx.foobar.org:8686 -c secret queue retry -c [email protected] -d example1.com -t "2023-11-20T05:04:00Z"
Successfully rescheduled 4 message(s).
Cancel
The queue cancel command cancels the delivery of a message. It is also possible to partially cancel the delivery to just one or multiple recipients. The accepted options are:
$ stalwart-cli -u https://mx.foobar.org:8686 -c secret queue cancel --help
Cancel delivery
Usage: stalwart-cli queue cancel [OPTIONS] [IDS]...
Arguments:
[IDS]...
Options:
-s, --sender <SENDER> Apply to messages matching a sender address
-r, --rcpt <RCPT> Apply to specific recipients or domains
-b, --before <BEFORE> Apply to messages due before a certain datetime
-a, --after <AFTER> Apply to messages due after a certain datetime
-h, --help Print help
For example, to cancel the delivery on an entire message:
$ stalwart-cli -u https://mx.foobar.org:8686 -c secret queue cancel 42B91F716
Cancelled delivery of 1 message(s).
Or, to just cancel the delivery to a particular recipient using a filter:
$ stalwart-cli -u https://mx.foobar.org:8686 -c secret queue cancel -s [email protected] -r [email protected]
Cancelled delivery of 5 message(s).