Search all skrzynka documentation

Invocation#

text

skrzynka mailbox declare --skarbiec-item <ID>

Purpose#

Declare one Skarbiec item a mailbox: tag it skrzynka:mailbox in Skarbiec and import every INBOX message. Skarbiec owns the mailbox list; this command edits that list and reads the result.

Inputs and options#

Input or option	Required	Meaning
`--skarbiec-item <ID>`	Yes	Existing canonical `login` or complete account `bundle` item, non-whitespace characters. Only the item reference crosses the CLI boundary; the address, display name and server settings come only from the item. Reception uses IMAP IDLE, not a mailbox poll interval.

Global options accepted on this path are --organization <ID> (required on every command except serve, version and onboarding; none is assumed), --skarbiec-bin <PATH> (default skarbiec) and --text (print results as path: value lines for people instead of JSON).

Output and state effect#

Reads the item's profile and credential, adds the tag skrzynka:mailbox while keeping the item's other tags (skarbiec retag), then fetches every unseen INBOX UID in ascending order and commits each supported message with the UID cursor past it; the first commit adopts the mailbox. The JSON result contains applied, source kind and item reference, mailbox_state, the public mailbox, imported/unchanged/conflicting/rejected message counts, and rejected_by_reason. A fetch failure part way keeps what was committed; skrzynka sync continues from the cursor. An equal retained UID is unchanged; the provider is never mutated and no credential or message body appears in the result.

Refusals#

Missing --skarbiec-item or profile options such as --email are refused by Clap with exit 2. Account settings belong in Skarbiec.
MAILBOX_PROFILE_INVALID identifies missing or invalid Skarbiec profile fields, for example Skarbiec item must supply imap_host; the item is not tagged. Invalid supplied ports and security are refused rather than replaced with defaults.
Credential resolution failures leave mailbox data unchanged. SKARBIEC_WRITE_FAILED names the item Skarbiec refused to retag.
IMAP authentication, connection or search failures before importing a message do not advance the cursor. A later fetch failure preserves already committed messages and their cursor. The tag stays, so the next sync resumes from persisted progress.
MAILBOX_IMPORT_PROFILE_CONFLICT refuses a changed receiving address or IMAP endpoint because the retained UID cursor cannot be reused. MAILBOX_IMPORT_CONFLICT refuses differing normalized content for one provider UID. Refusals preserve the retained mailbox, messages, and cursor.