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

This documentation is primarily geared towards developers rather than end-users. (Operators looking to run the mail services themselves should start at Running a mail server.) To follow the examples, you’ll need the sithbit CLI built from the SithBit workspace: clone the repo and build it with cargo build -p mail-client -r, which produces the sithbit binary at target/release/sithbit.

Talking to the chain also needs an RPC endpoint. Configure one with sithbit config set --url <cluster> (e.g. https://api.devnet.solana.com), or point a JSON_RPC_URL environment variable at one directly.1

Creating a wallet

You’ll need a cryptographic keypair / wallet; its public key becomes your first email address. sithbit can generate one directly:

sithbit wallet create
# Wallet keypair written to '/home/you/.config/solana/id.json'
# Address: 85FZrun1Eb5bdkbFCDjaFSTLnBfnx6sUFHa5BiYH2Q03

By default this writes to the path sithbit config get reports as your keypair path.2 Pass --outfile <path> to write elsewhere; sithbit wallet create refuses to overwrite an existing keypair file unless you also pass --force.

Even though there is no domain portion of the address, i.e., 85FZrun1Eb5bdkbFCDjaFSTLnBfnx6sUFHa5BiYH2Q03@sithbit.com, your standalone public key address is already a legitimate email address in the system, although you will need to create a mailbox for it and at least one frombox before emails can be routed to your address. A frombox is keyed by a pair: your wallet address as the recipient, and a sender’s “from” address — but only the recipient side needs to be an on-chain wallet. The sender’s “from” address is just a plain, off-chain RFC822-compliant address string (e.g. jane_doe@sithbit.com, or any other domain) — it never has to resolve to a Solana keypair.

How mail reaches an address: a sender’s From Address — an off-chain RFC822 string, not a wallet — is checked against the recipient’s Frombox for stamps, SendMail consumes one and delivers the message, the Frombox is keyed by both that From Address string and the recipient’s on-chain Wallet Address, and the Wallet Address separately owns exactly one Mailbox via mailbox create.

Neither step above needs the Solana CLI/SDK installed at all — sithbit config and sithbit wallet create are a complete substitute for it in this workflow.

  1. If you already have the Solana CLI installed, solana config set --url <cluster> writes the same config file. ↩

  2. If you already have the Solana CLI/SDK installed, solana-keygen new followed by solana-keygen pubkey gets you the same keypair file and address. ↩