| SHARDPOSTCTL-MAILBOX(1) | ShardPost Manual | SHARDPOSTCTL-MAILBOX(1) |
NAME
shardpostctl-mailbox - list, inspect, create, rename and subscribe mailboxes
SYNOPSIS
shardpostctl mailbox list [-all] [-limit
n] [-after name] [--json] account
shardpostctl mailbox show [--json] account mailbox
shardpostctl mailbox create [-special-use list]
account name
shardpostctl mailbox rename [-if-match etag] account
mailbox new name
shardpostctl mailbox subscribe [-if-match etag]
account mailbox
shardpostctl mailbox unsubscribe [-if-match etag]
account mailbox
shardpostctl mailbox lock status [--json]
shardpostctl mailbox lock enable -pods n [-force]
[--json]
shardpostctl mailbox lock disable [--json]
DESCRIPTION
A mailbox argument is either the mailbox name as the client sees it (INBOX, Archive/2026) or its stable id. The client resolves a name to its id first, so a mailbox that is renamed between two commands is still the same object.
mailbox list
Mailboxes in name order with id, UIDVALIDITY, UIDNEXT, HIGHESTMODSEQ, subscription, special-use and the number of ACL entries. One page holds -limit entries (default 100); -after continues after a name, and -all fetches every page. This command reads the registry and one header per mailbox, so it stays cheap even for large accounts.
Role: diagnose.
mailbox show
One mailbox in detail. On top of the listing it reports the message count, how many are unseen and flagged deleted, the total size, the number of index shards and their size, where the change log starts (the QRESYNC horizon) and the keywords in use. It reads every index shard of the mailbox, so it costs more than mailbox list.
The shard line is worth knowing: shards 47 of 20 UIDs means the mailbox was created when mbox_shard_size was 20. The size is fixed when the mailbox is created and never changes afterwards; only a rebuild (export, purge, restore) moves an existing mailbox to the current size.
Role: diagnose.
mailbox create
Creates a mailbox, with parents as needed. -special-use takes a comma-separated list (\Archive, \Sent, \Junk, \Trash, \Drafts, \All, \Flagged, \Important); it is stored in the usual spelling. If the mailbox already exists with the same special-use, the command succeeds and changes nothing, so a repeated run after a lost answer is safe. With a different special-use it is a conflict.
Role: provision.
mailbox rename
Renames a mailbox together with its children. INBOX cannot be renamed, and an existing target is a conflict. Renaming to the current name does nothing.
Role: provision.
mailbox subscribe, mailbox unsubscribe
Sets or clears the subscription flag that clients use to decide which mailboxes to show.
Role: provision.
mailbox lock status
Shows whether the cluster mark of the mailbox lock (mailbox/lock, since 0.52.0) is set, with the server registrations as fts layout3 status shows them. The mark allows the mailbox_delete job (see shardpostctl-job(1)) to lock only the mailboxes it removes instead of the whole account: deliveries, logins and sessions go on, a write into a locked mailbox is refused, a Sieve fileinto into one goes to INBOX, and only a session that has one selected is closed. A server before 0.52.0 does not see the lock and would deliver into a mailbox that is being deleted, so the mark needs every server to know it. Without the mark the job takes the account lock, as before 0.52.0. Role: diagnose.
mailbox lock enable
Sets the mark when exactly n fresh registrations of servers report the capability mailbox_lock; otherwise it is refused with exit code 65 naming the instances. -force sets it without the check (audited). Plans with -online are allowed from then on, and with jobs.mailbox_delete_online: auto also plans without it. Role: repair.
mailbox lock disable
Removes the mark: new plans take the account lock, a plan with -online is refused. Runs that started finish; before a downgrade to a version before 0.52.0 wait for them (or cancel the jobs, which unlocks their mailboxes). Role: repair.
OPTIONS
- -limit n
- Mailboxes per page (mailbox list), 1 to 1000; 100 by default.
- -after name
- Continue the listing after this mailbox name.
- -all
- Fetch every page.
- -special-use list
- Special-use attributes of a new mailbox, comma-separated. A client finds such a mailbox by its attribute rather than by its name, which is what makes "Drafts" work in a client that calls it something else. The server creates \Drafts, \Sent, \Trash, \Junk and \Archive for every account on its own, which server.autocreate configures, so this flag is for the rest: RFC 6154 also defines \All and \Flagged, RFC 8457 defines \Important. The value is stored as given; the server does not check that no other mailbox of the account carries the same attribute.
- -if-match etag
- Make the change conditional. The ETag is printed by every command that changes a mailbox; if the mailbox changed meanwhile, the server refuses with exit code 65 instead of overwriting someone else's change.
- -pods n
- mailbox lock enable: the number of servers running now (required).
- -force
- mailbox lock enable: set the mark without the registrations check (audited).
- --json
- Print the answer as JSON.
EXAMPLES
Public folders are administered like an account, with ~public as the account. They belong to nobody, so nobody has rights on them until an entry grants some; see shardpostctl-acl(1).
shardpostctl mailbox create '~public' Announcements shardpostctl acl set '~public' Announcements anyone lr shardpostctl mailbox list -all '~public'
Which mailboxes does the account have, and how big is the INBOX?
shardpostctl mailbox list -all user@example.org shardpostctl mailbox show user@example.org INBOX
Create an archive mailbox for a user who asked for one:
shardpostctl mailbox create -special-use '\Archive' \
user@example.org Archive
Rename a mailbox, but only if nobody else changed it since you looked:
shardpostctl mailbox show user@example.org Projekte # prints the etag shardpostctl mailbox rename -if-match '"m-0808d3b73bb67293"' \
user@example.org Projekte Projects
Make a mailbox visible in the client:
shardpostctl mailbox subscribe user@example.org Projects
Deleting a mailbox is not done here. It is a planned job, so you can see what would be removed before anything happens; see shardpostctl-job(1):
shardpostctl plan -mailbox 'Archive/2019' mailbox_delete user@example.org
EXIT STATUS
- 0
- Done.
- 65
- Conflict, or the ETag no longer matches.
- 67
- No such account or mailbox.
- 73
- The account is at its mailbox limit (limits.mailboxes or limits.mailbox_names in the server configuration; error limit_exceeded).
- 77
- The caller lacks the role.
SEE ALSO
shardpostctl(1), shardpostctl-acl(1), shardpostctl-job(1), shardpostctl-message(1)
| 2026-10-03 | ShardPost 0.51.0 |
Rendered from docs/man/man1/shardpostctl-mailbox.1 in the ShardPost repository.