shardpostctl-submission(1)

SHARDPOSTCTL-SUBMISSION(1)

ShardPost Manual

SHARDPOSTCTL-SUBMISSION(1)

NAME

shardpostctl-submission - list and cancel delayed JMAP submissions of an account

SYNOPSIS

shardpostctl submission list [-json] account
shardpostctl submission list -all [-json] [-after key] [-limit n]
shardpostctl submission cancel [-json] account id

DESCRIPTION

A JMAP client can ask for a message to be released later (EmailSubmission with the FUTURERELEASE parameter HOLDFOR or HOLDUNTIL). Such a submission waits in the submission queue of the cluster until its release time; then a worker sends a copy of the message that was taken when it was created. These commands show the submissions an account has waiting and cancel one for the user.

Delayed sending is offered with jmap.submission.delayed.max_delay_seconds; the queue needs the admin store indexes (admin.kv_index write or read). Without them both commands fail with exit status 75.

submission list

Lists the submissions the account still holds a message copy for, by release time: pending, being sent, or ended and not yet cleaned up. Each line names the submission id, its state (pending, sending, final, canceled, failed), the release time, the attempts so far, the size and the envelope. The list is read from the account's own records, without a listing of the cluster. Role: diagnose.

With -all it lists the records of every account instead, in key order, a page at a time. This lists the admin namespace of the cluster (one listing per page, which visits every placement group of the pool): use it for diagnosis and to check that the queue is empty before going back to a release older than 0.43.0, not routinely. It also shows a record whose message copy and queue entry were lost, which the per-account list cannot see. Role: diagnose with the scope of all accounts.

submission cancel

Cancels a pending submission as a JMAP client would (undoStatus canceled): the message is not sent, its copy is deleted, and the user's EmailSubmission shows canceled. The record names who canceled it (admin:identity). A submission that the worker has begun to send cannot be canceled any more (exit status 65); one that has ended and was cleaned up is not found (exit status 67). Tell the user: their client shows the submission as canceled. Role: support.

OPTIONS

-json: Print the answer as JSON.
-all: list: the records of every account (see above).
-after key: list -all: continue after this key (printed as more: at the end of a full page).
-limit n: list -all: records per page, 1 to 1000 (100).

EXAMPLES

A user asks why a message they scheduled has not gone out yet:

shardpostctl submission list user@example.org

The user scheduled a message to the wrong recipients and cannot reach their client; cancel it:

shardpostctl submission cancel user@example.org S5f0c1e2d3b4a5f6e7d8c9b0a

Before going back to a release older than 0.43.0 the queue has to be empty; check every account:

shardpostctl submission list -all

What one account still has waiting, as JSON:

shardpostctl submission list -json user@example.org | jq -r '.items[] | "\(.id) \(.state) \(.release)"'

EXIT STATUS

0: Done.
64: Wrong arguments, or the account or id is not valid.
65: The submission is no longer pending (it is being sent or has been sent).
67: No such submission (it may have ended).
70: An unexpected answer from the server.
75: The server cannot be reached, or it has no submission queue (try again, or check admin.kv_index).
77: The caller lacks the role diagnose (list) or support (cancel), may not address the account, or lacks the scope of all accounts (list -all).