Search all skrzynka documentation

First-success fact#

For the CLI and loopback API, first success is a completed mailbox declare result with at least one supported provider message imported or retained unchanged. For Skrzynka Desktop, the shared journey observes the same provider-backed mailbox state through last_sync_at. Installation, sign-in, a healthy process, explanatory navigation, or selecting an item alone is not first success.

Zero state#

skrzynka help performs no network access and creates no state. It explains the product, names Skarbiec and mailbox prerequisites, and gives the safe sequence: start locally, declare one existing Skarbiec item a mailbox, inspect messages. skrzynka serve may create the local state directory and database but refuses a non-loopback bind address.

Machine journey#

Inspect: skrzynka status reports database path, version, mailbox count, message count, and whether skarbiec can be found. It never resolves a credential.
Select authority: for a generic mailbox, choose one existing Skarbiec item by exact ID; for Gmail, Skrzynka Desktop lists deduplicated Google identities resolved from Skarbiec login metadata.
Declare the existing mailbox: skrzynka mailbox declare --skarbiec-item ITEM_ID tags the item skrzynka:mailbox in Skarbiec, resolves the credential internally, and imports every INBOX message, committing each with the UID cursor past it. Gmail OAuth is an alternative connector when the configured Desktop-app client accepts the chosen loopback callback.
Continue after a failure: run skrzynka sync; it continues from the committed cursor. Equal provider UIDs are unchanged; conflicts and invalid input leave retained state untouched.
Observe success: skrzynka message list --mailbox MAILBOX_ID shows the imported messages, while the declare result preserves rejection reasons and counts.
Reply when intended: skrzynka message reply MESSAGE_ID --body-file PATH presents the provider-facing side effect before sending and returns terminal or ambiguous state.
Originate when intended: skrzynka message send --mailbox MAILBOX_ID_OR_ADDRESS --to ADDRESS --subject TEXT --body-file PATH claims an outbound message by its idempotency key, then returns the same terminal or ambiguous state; skrzynka message outbound reads it back.

The CLI is noninteractive. Automation receives one JSON object on stdout and a nonzero exit for failure; decorative human output is never required for parsing.

Human desktop journey#

Shared Wisent authentication first restores or establishes a real identity and selected organization. The private skrzynka-desktop client then runs the Echo-owned, version-bound skrzynka-desktop.first-use journey:

Screen	Entry evidence	Completion evidence	Safe fallback
Welcome	Authenticated organization selected	Operator chooses the unified inbox workflow	Exit without mailbox state change
Service	Product promise understood	Authenticated `/v1/status` succeeds for the selected organization	Retry without advancing
Mailbox declaration	Service ready	Core tags the selected Skarbiec item and atomically retains its first validated provider page	Preserve prior state and show imported, unchanged, conflicting, and rejected counts
Retained result	Declaration accepted provider-backed state	`last_sync_at` and the committed UID cursor are readable	Declare again without duplicating retained UIDs

The canonical bundled journey version is 2026-09-04.1. The desktop runs it through Echo's shared WisentOnboarding package, persists version-bound progress and idempotent events locally, and uses the validated bundled definition when the central transport is unavailable. When the Stado integration transport is configured, bundle reads and event collection use the centralized Echo onboarding boundary. Analytics failure never blocks the core mailbox workflow.

Common failures#

Failure	Meaning	Recovery
`SKARBIEC_UNAVAILABLE`	CLI missing or cannot run	Install/start the supported Skarbiec release and re-run status
`SKARBIEC_ITEM_INVALID`	Item missing, unreadable, or lacks required credential fields	Correct the exact item or select another; no mailbox row is created
`GMAIL_OAUTH_REJECTED`	Google or the operator rejected the bounded authorization	Start a fresh connection flow; no partial authorization is used
`GMAIL_OAUTH_ACCOUNT_MISMATCH`	Google returned a different account than the selected Skarbiec identity	Authorize the exact selected address
`GMAIL_AUTHORIZATION_EXPIRED`	Google rejected the saved refresh token with invalid_grant	Reconnect the same Gmail profile; local messages remain readable
`AUTHENTICATION_REQUIRED`	The Wisent session is absent or invalid	Return to shared sign-in; no organization data is returned
`ORGANIZATION_ACCESS_DENIED`	The selected organization is not one of the signed-in account's memberships	Select an authorized organization; no mailbox state is read or changed
`IDENTITY_UNAVAILABLE`	Central identity verification could not complete	Retry after the identity service recovers; the core fails closed
`MAILBOX_PROFILE_INVALID`	Required host/address/security setting is absent or contradictory	Supply non-secret settings or update the bundle
`IMAP_AUTHENTICATION_FAILED`	Provider refused the current credential	Rotate or correct the Skarbiec item, then retry sync
`IMAP_UNAVAILABLE`	TLS, DNS, connection, or provider failure	Inspect mailbox status and retry; other mailboxes continue
`SMTP_REJECTED`	Provider rejected the message before acceptance, and repeats its own refusal text	Correct the provider/account condition and use a new idempotency key
`REPLY_UNCERTAIN` / `OUTBOUND_UNCERTAIN`	Process stopped after send began without terminal evidence	Inspect provider Sent mail; no automatic resend occurs
`MAILBOX_SELECTOR_AMBIGUOUS`	The `--mailbox` address names more than one mailbox	Repeat with the exact mailbox id the refusal prints

Reset and removal#

mailbox remove deletes the selected mailbox's retained messages, replies and outbound records in the fleet database after undeclaration and explicit confirmation. It never deletes the Skarbiec item or provider mailbox. There is no local SQLite reset: do not remove files or reset a shared database to recover one mailbox. Inspect the selected organization and mailbox before using the documented removal command.