Search all skrzynka documentation

Overview#

This transcript was captured from the source-built 0.2.0 binary in an isolated temporary database. --skarbiec-bin pointed to a stand-in CLI that returned the canonical skarbiec.item.v2 bundle for team-inbox; IMAP/SMTP ports were deliberately unreachable, so no operator state or provider was touched.

1. Inspect an empty database#

console

$ skrzynka --database "$STATE/skrzynka.db" status
{
  "product": "skrzynka",
  "version": "0.2.0",
  "database_path": "/var/folders/4m/g5zcy_y57jgfk_cg9dqt10w00000gn/T/skrzynka-docs.15ebyxek/state/skrzynka.db",
  "schema_version": 4,
  "mailbox_count": 0,
  "enabled_mailbox_count": 0,
  "message_count": 0,
  "poll_interval_seconds": 60,
  "skarbiec_available": true
}

The probe created the state directory and schema, but resolved no item.

2. Declare the bundle in Skarbiec#

console

$ skarbiec retag team-inbox --tags skrzynka:mailbox
$ skrzynka --database "$STATE/skrzynka.db" mailbox list

mailbox list read the declaration and returned one mailbox for team-inbox: enabled: true, last_uid: 0, and the address and servers from the item. No secret is in the returned resource, and listing again returns the same UUID rather than a second mailbox.

3. Synchronize all enabled mailboxes#

console

$ skrzynka --database "$STATE/skrzynka.db" sync
{
  "completed_at": "2026-08-24T23:09:24.159599+00:00",
  "mailboxes": [
    {
      "mailbox_id": "3a9f65f0-a6e1-4520-bd35-708731a6a92f",
      "ok": false,
      "summary": null,
      "error_code": "IMAP_UNAVAILABLE",
      "error_message": "IMAP server could not be reached over TLS"
    }
  ]
}

The command exited 0 because all-mailbox synchronization completed and represented the per-mailbox failure in JSON. The mailbox retained the evidence:

json

{
  "last_uid": 0,
  "last_sync_at": null,
  "last_error_code": "IMAP_UNAVAILABLE",
  "last_error_message": "IMAP server could not be reached over TLS"
}

A selected single-mailbox sync instead exited 1 with the standard retryable envelope:

console

$ skrzynka --database "$STATE/skrzynka.db" sync --mailbox 3a9f65f0-a6e1-4520-bd35-708731a6a92f
{"error":{"code":"IMAP_UNAVAILABLE","message":"IMAP server could not be reached over TLS","retryable":true}}

4. Exercise state transitions#

Removing a declared mailbox is refused with MAILBOX_STILL_DECLARED. mailbox undeclare <UUID> removed only the skrzynka:mailbox tag and returned the same resource with enabled:false and last_error_code: MAILBOX_NOT_DECLARED; the UUID and cursor stayed intact. Removal without confirmation then failed exactly:

console

$ skrzynka --database "$STATE/skrzynka.db" mailbox remove 3a9f65f0-a6e1-4520-bd35-708731a6a92f
{"error":{"code":"CONFIRMATION_REQUIRED","message":"mailbox removal requires --confirm","retryable":false}}

With confirmation:

console

$ skrzynka --database "$STATE/skrzynka.db" mailbox remove 3a9f65f0-a6e1-4520-bd35-708731a6a92f --confirm
{
  "removed": "3a9f65f0-a6e1-4520-bd35-708731a6a92f"
}

Only the isolated SQLite rows were removed; the stand-in item was untouched. For a real controlled inbox, continue with the getting-started example.