Mailbox

Overview#

A mailbox is one Skarbiec item tagged skrzynka:mailbox, as Skrzynka uses it. Skarbiec owns the list and every account value; Skrzynka keeps the mail it imported and where synchronization stands. A mailbox belongs to one organization, points to a required receiving Skarbiec item and optionally to a different sending item, reads INBOX over IMAP, and sends over SMTP — both replies to what it received and outbound messages it originates. When the sending reference is absent, both protocols use the receiving item.

Shape#

The public JSON resource contains:

The stored organization_id is deliberately omitted from serialization. Passwords, authentication usernames, access tokens, refresh tokens, and service-account keys are not columns.

Declaration and profile#

Skarbiec owns the mailbox list. A Skarbiec login or bundle item is a mailbox exactly when it carries the tag skrzynka:mailbox. Tag the item in Skarbiec (skarbiec retag <ID> --tags ...,skrzynka:mailbox) or run skrzynka mailbox declare --skarbiec-item <ID>; Skrzynka keeps no list of its own. Every profile value comes from the item, then these defaults:

• display_name: mailbox email;
• imap_port: 993;
• smtp_security: starttls;
• smtp_port: 587 for starttls, 465 for tls.

email, imap_host, and smtp_host must exist in the item. A username containing @ can supply the email. CLI and API values never override the item.

The two references separate authentication from public identity. A public mailbox address may be an alias delivered to an account with a different login name: the item's username is the login and its email is the public address. IMAP resolves skarbiec_item_id, while replies and originated mail keep email as From and resolve smtp_skarbiec_item_id.

Lifecycle#

Every mailbox list, sync, and background poll reconciles with Skarbiec first. A newly declared item becomes a mailbox with last_uid: 0; profile changes of a declared item are adopted on the same UUID; a mailbox whose item lost the tag becomes enabled: false with last_error_code MAILBOX_NOT_DECLARED and keeps its mail. Tagging the item again resumes the same UUID and cursor. The background poll never creates a mailbox, because only a caller knows its organization. Successful synchronization advances the cursor and clears its error; failure records an error without advancing last_sync_at.

Removal deletes local mail only for a mailbox Skarbiec no longer declares, requires explicit confirmation, and cascades through local messages, reply attempts, and outbound messages. It does not change Skarbiec or the provider mailbox.

Invariants and refusals#

• One receiving Skarbiec item stands for at most one mailbox. A sending item may be referenced by more than one row.
• A mailbox whose item no longer carries the tag: MAILBOX_NOT_DECLARED — Skarbiec item '<ID>' does not carry skrzynka:mailbox; Skrzynka keeps its mail and no longer polls it.
• Removing a declared mailbox: MAILBOX_STILL_DECLARED — Skarbiec item '<ID>' still carries skrzynka:mailbox; undeclare the mailbox before removing its local mail.
• A missing row is indistinguishable across organizations: NOT_FOUND — mailbox was not found.
• display_name must contain 1–200 characters.
• Email must parse as an address.
• Hosts must be at most 253 characters, contain no whitespace, and contain no URL scheme.
• Ports must be nonzero.
• The poll interval must be 15–86400 seconds.
• Invalid profile data uses MAILBOX_PROFILE_INVALID; invalid global service polling uses POLL_INTERVAL_INVALID.
• A mailbox may be selected by id or by its own address when originating mail, and an address is only a usable selector while it names one mailbox: MAILBOX_SELECTOR_AMBIGUOUS — <SELECTOR> names <COUNT> mailboxes (<ID>, <ID>); select one by id.

See Skarbiec item, synchronization, outbound message, and the CLI reference.