shardpostctl-message(1) – ShardPost docs

SHARDPOSTCTL-MESSAGE(1)

ShardPost Manual

SHARDPOSTCTL-MESSAGE(1)

NAME

shardpostctl-message - list, search, show, export, flag, copy and move messages

SYNOPSIS

shardpostctl messages [-after-uid n] [-limit n] [--json] account mailbox
shardpostctl search [criteria] [-limit n] [-after cursor] [--json] account
shardpostctl message show [-uidvalidity v] [--json] account mailbox uid
shardpostctl message export [-uidvalidity v] account mailbox uid
shardpostctl flags [-add list] [-remove list] [-unchanged-since modseq] [-uidvalidity v] account mailbox uids
shardpostctl copy [-uidvalidity v] account mailbox uids destination
shardpostctl move [-uidvalidity v] account mailbox uids destination

DESCRIPTION

These are the support tools for single messages. A message is addressed by mailbox, UIDVALIDITY and UID, so a mailbox that was deleted and recreated in the meantime cannot answer with a different message: the server refuses with exit code 65.

Without -uidvalidity the client reads the mailbox's current value first. That is convenient, but it only protects you against a change between the client's two requests. When it matters, pass the value you saw in an earlier listing.

uids is a comma-separated list, for example 42, 42,43,50. UIDs that no longer exist are reported as missing instead of failing the whole request.

messages

Message metadata of one mailbox in UID order: UID, size, internal date, MODSEQ and flags. No headers, no content, so the role diagnose is enough. Page with -after-uid.

search

Searches one mailbox (-mailbox) or the whole account. Criteria are combined with AND:

-from text
-to text
-subject text: Case-insensitive substring of the envelope. -to also matches Cc.
-message-id id: Exact Message-ID, with or without angle brackets.
-text words: Full-text search over headers and body. This needs the full-text index; while it is being rebuilt, or if it was never built, the search finds nothing.
-since date
-before date: Internal date, as 2026-09-01 or RFC 3339.
-flag list
-not-flag list: All of these flags are set, or none of them is.

A search examines at most admin.search_scan_limit messages (50000 by default) and returns at most -limit hits (50 by default, 200 at most). If it stops early it prints a cursor; pass it to -after to continue. The audit log records which criteria were used, never their values. Role: content.

message show

Envelope and header section of one message, with its flags, size, dates and MODSEQ. The body is not printed. Role: content.

message export

Writes the message as stored (RFC 5322) to standard output. Redirect it into a file to hand it to someone or to feed it into another tool. Role: content.

flags

Adds and removes flags, like IMAP STORE. -add and -remove take comma-separated lists; system flags are written as \Seen, \Answered, \Flagged, \Deleted, \Draft, keywords as themselves ($Junk, $NotJunk, $Forwarded). \Recent cannot be set. -unchanged-since skips every message whose MODSEQ is higher, which is the CONDSTORE rule: those UIDs come back as modified and keep their flags.

In a public folder (~public) \Seen is the shared default: it is what everyone sees who has not read the message yet, and setting it here does not mark the message read for one particular person — each account keeps its own mark, in its own namespace, and that mark wins from the moment it exists. Role: support.

copy, move

Copies or moves messages into another mailbox of the same account. The result maps every source UID to its new UID, as IMAP UIDPLUS does. move removes the messages from the source mailbox in the same step. Role: support.

Deleting messages for good is not done here; it is a planned job, see shardpostctl-job(1).

OPTIONS

-uidvalidity v: UIDVALIDITY the UIDs belong to. Default: the mailbox's current one.
-limit n: Messages per page (messages: 100 by default, up to 1000) or hits per page (search: 50 by default, up to 200).
-after-uid n: Continue a message listing after this UID.
-after cursor: Continue a search at the cursor the previous page printed.
--json: Print the answer as JSON.

EXAMPLES

What is in the INBOX, and since when?

shardpostctl messages -limit 20 user@example.org INBOX

"I never got the invoice from September": find it, then look at it.

shardpostctl search -subject Rechnung -since 2026-09-01 user@example.org
shardpostctl message show user@example.org INBOX 933

Hand a message to someone as a file, exactly as it is stored:

shardpostctl message export user@example.org INBOX 933 > 933.eml

A message was marked as spam by mistake: take the flag off and move it back:

shardpostctl flags -remove '$Junk' -add '$NotJunk' \


    user@example.org Junk 42
shardpostctl move user@example.org Junk 42 INBOX

Mark a batch as read, but only if nothing changed since you looked (MODSEQ from shardpostctl messages):

shardpostctl flags -add '\Seen' -unchanged-since 940 \


    -uidvalidity 1789726963 user@example.org INBOX 930,931,932

Find everything still flagged deleted, then expunge it as a planned job:

shardpostctl search -mailbox Trash -flag '\Deleted' user@example.org
shardpostctl plan -mailbox Trash -deleted expunge user@example.org
shardpostctl apply -wait <plan-id>

EXIT STATUS

0: Done.
65: The UIDVALIDITY does not match: the mailbox is not the one you addressed.
67: No such account, mailbox or message.
73: The copy would exceed the quota, or the change would give the target mailbox more keywords than limits.keywords_per_mailbox allows (error limit_exceeded).
77: The caller lacks the role (diagnose, content or support).