Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Getting started

Start with the standalone get-started page or any SithBit client: the webmail app, Thunderbird extension, Outlook add-in, or Chrome extension. They all use the same five-step wizard: create or import a wallet, choose your inbox price, and claim a mailbox with an optional handle. You do not need the command line.

If you prefer a terminal, sithbit setup provides the same guided flow, and sithbit earnings shows what a configured recipient’s wallet holds and has earned.

Web onboarding: the browser wizard

The wizard is what a brand-new user sees first: until it finishes, the client hides its normal wallet manager and mail UI and shows only these five steps.

  1. Welcome — your wallet. Your wallet address is your email address, so the first thing the wizard needs is a wallet. Three paths:

    • Create a new wallet. A fresh Solana keypair is generated entirely in your browser by a WebAssembly module compiled from this workspace’s own crates — the secret never touches a server. The wizard shows that secret key exactly once with a plain warning: save it now, because it is the only copy — lose it and your mailbox is gone forever. You must tick “I have saved my secret key” before you can go on. Copy it somewhere safe (a password manager) before continuing.
    • Import an existing keypair. Paste a Solana keypair file — the same JSON array of 64 numbers sithbit wallet create writes — to reuse a wallet you already own.
    • Connect Phantom or Ledger. If you already use a browser or hardware wallet, connect it instead of importing its key into the SithBit page. Your wallet’s signing key never enters the page — it stays in the extension or on the hardware device, and you approve the mailbox create there. This button only appears when a compatible wallet extension is present. Because a hardware wallet cannot itself open sealed mail, this path also creates a separate reading key — see below.

    For the create/import paths you then choose a passphrase, typed twice. The wallet is encrypted under that passphrase before it is stored in the client (PBKDF2 + AES-GCM in the browser’s local storage); the decrypted key lives only in memory for the session, so the client asks for the passphrase again next time. The passphrase is not a recovery phrase — it protects the stored copy, but only the secret key from the create step can restore the wallet elsewhere.

    The second field is a confirmation, and Save stays disabled until the two agree. This is not ceremony: a mistyped passphrase seals the wallet successfully and fails only later, at unlock, by which point the correct passphrase is whatever you typed once, unseen. An eyeball toggle beside each field reveals what you typed, so you can check it before committing.

    The connect-wallet reading key (honest trade-off). SithBit mail is sealed to the recipient, and a Phantom/Ledger wallet can sign but cannot decrypt — its key never leaves the device. So when you connect an external wallet, the wizard generates a separate delegated reading key in your browser and publishes its public half on-chain (senders seal to it). It is revealed once to save, exactly like a fresh keypair, and protected by a passphrase at rest. The trade-offs, stated plainly:

    • Your funds-holding wallet key stays off the browser — only this low-value, mailbox-scoped reading key is browser-held. That is the point of the path.
    • If you lose the reading key, you lose the ability to read already received mail — but not your wallet, your funds, or your mailbox. You can rotate to a new reading key (mailbox set-key) and keep receiving.
    • A recoverable, seed-derived reading key (no separate secret to save) is a planned improvement; for now the reading key is a distinct secret you save, just like a keypair.

  2. Claim your handle. Optionally register a human-readable alias — yourhandle — so senders can mail yourhandle@sithbit.com instead of your raw base58 address. Leave it blank and people simply address mail to your wallet directly; you can always claim a handle later. You may also set the sending domain here (blank uses the protocol default, sithbit.com).

  3. Set your price. Choose the default postage — the amount, in SOL, that an unknown sender must prepay for each message. Strangers pay it, and you keep roughly 90% of the settled postage. For people you know, you can lower the price per sender or fund their postage yourself (see Economics and Fromboxes). The initial 1 SOL value is deliberately a wall, not a suggested everyday price: it keeps unknown senders out until you choose a lower rate. If you want to be reachable by people you don’t know yet, or findable by campaigns that pay you to be reached, set a lower default here. An optional checkbox keeps your message bodies off public IPFS and in your operator’s local storage instead.

  4. Review. The wizard shows the handle, domain, and default postage it is about to commit, so you can step back and adjust before anything lands on-chain. If the wallet you chose already owns a mailbox, it says so here rather than trying to create a second one. The wizard also checks the wallet’s on-chain balance at this point: because a mailbox create pays a little SOL (the account rents, plus the alias claim fee when you claimed a handle — length-tiered, so a premium 1–4 character handle raises the figure to match its scarcity price), a wallet that can’t cover it gets a plain-language warning here — naming the wallet, what it holds, and how much more to transfer — instead of a raw chain error at the last step. The warning does not block you: you can fund the wallet out of band and go on.

  5. Finish. One click mints your mailbox on-chain. If you claimed a handle in step 2, the mailbox create and the alias create ride the same transaction — one signature, one confirmation. On the create/import paths the transaction is built and signed client-side in the wasm module and only the finished, signed transaction is relayed; the server never sees your key. On the connect-wallet path the same bundle — mailbox create, the optional alias, and publishing your delegated reading key — is a single approval in Phantom or Ledger; the wallet signs and submits it. When it confirms, the client swaps out of the wizard and into its normal mail-and-settings UI. If the wallet turns out to be unfunded, the create is refused with the same plain-language funding message rather than the node’s raw “debit an account” error.

Because your wallet is your account, there is no “sign up” step and no server-side password — the five steps above are the whole account. A returning user never sees the wizard: a client that already has a stored wallet asks only for the passphrase to unlock it (and reconnects the extension, on the connect-wallet path), and a wallet that already owns a mailbox goes straight to the normal UI. The per-client specifics of that routing — and where each client reads its server and RPC endpoints — are on the webmail, Thunderbird, Outlook, and Chrome pages.

Onboarding a second wallet from inside a client. The wizard is not only a first-run flow. Once you are signed in, each mail client’s dashboard carries an “Add another wallet” button that re-opens the wizard for a fresh wallet — so an existing user can stand up a second mailbox (a new keypair, or another connected wallet) without forgetting the one they already use. Finishing the new wallet returns you to the normal UI, now able to switch between them.

A standalone get-started page

The same wizard is also served on its own, as a standalone get-started page you can point a brand-new user at directly — a single shareable URL, with no mail client installed. It runs the identical five steps and, like the standalone marketplace page, is served by account_api from a [[static]] mount whose root is the built webclients/onboarding/staging bundle (same origin as the API, so no CORS). When the mailbox lands, the page confirms the wallet is live and points the user at any SithBit client to sign in. It offers the same three wallet paths as the in-client wizard — create a fresh keypair, import one you already hold, or connect a Phantom/Ledger wallet (with the browser-held reading key described above) — so a brand-new user can complete onboarding end-to-end from this one page, with no mail client installed.

Self-service pages for refused senders

The same bundle carries two more standalone pages, aimed not at new users but at senders whose mail a SithBit server just refused — the pages the refusal replies link when the operator sets self_service_base_url:

  • fund.html — the funding page. Reached from a postage refusal (450 4.7.0 out of stamps / 550 5.7.0 no frombox). It resolves the recipient and quotes the stamp price trustlessly off the chain — postage plus the settlement surcharge plus the live protocol fee — then lets the sender connect Phantom or Ledger and buy stamps on the spot, creating the frombox if needed. The purchase is pinned to the price the page quoted, so a repricing between the quote and the click makes the buy refuse rather than charge the new rate.
  • dnd.html — the schedule page. Reached from a do-not-disturb refusal (450 4.2.1). It answers whether the recipient is accepting mail right now, and shows the away windows only for recipients who opted in to sharing them.

What each page tells the sender — and why refusing beats an autoreply in the first place — is on Do not disturb.

Both read their endpoints from two <meta> tags in the page head — sithbit-rpc-url (the Solana RPC node; both pages) and sithbit-api-url (the account API; the schedule page) — which an operator edits in the staged copy. Left empty, the pages fall back to the webmail app’s localStorage config keys and then the loopback dev defaults; the API default is the page’s own origin, so the normal deployment — the bundle served by account_api from a [[static]] mount, like the get-started page above — needs no setting at all.