Skip to content

Messages

The SMTP message queue is managed using the queue CLI command which accepts the following arguments:

$ stalwart-cli -u https://mx.example.org:8080 -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

Section titled “List”

The command queue list displays the messages awaiting to be delivered. It accepts the following filtering parameters:

$ stalwart-cli -u https://mx.example.org:8080 -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.example.org:8080 -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

Section titled “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.example.org:8080 -c secret queue status 52B91F716


+--------------+----------------------------------------------------------------------------------------------------------+
| ID           | 52B91F716                                                                                                |
+--------------+----------------------------------------------------------------------------------------------------------+
| Sender       | <>                                                                                                       |
+--------------+----------------------------------------------------------------------------------------------------------+
| Created      | Wed, 1 Mar 2023 11:44:22 +0000                                                                           |
+--------------+----------------------------------------------------------------------------------------------------------+
| Size         | 1127 B                                                                                                   |
+--------------+----------------------------------------------------------------------------------------------------------+
| Env-Id       | f                                                                                                        |
+--------------+----------------------------------------------------------------------------------------------------------+
|                                                                                                             example.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

Section titled “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.example.org:8080 -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.example.org:8080 -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.example.org:8080 -c secret queue retry -c [email protected] -d other-domain.example -t "2023-11-20T05:04:00Z"


Successfully rescheduled 4 message(s).

Cancel

Section titled “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.example.org:8080 -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.example.org:8080 -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.example.org:8080 -c secret queue cancel -s [email protected] -r [email protected]


Cancelled delivery of 5 message(s).