Create a mailbox

See Mailboxes for what a mailbox is, the settings it holds, and why creating one also claims a self-alias and carries an IPFS opt-out trade-off. This page covers the sithbit mailbox create command.

sithbit mailbox create \
  [--keypair <path>] \
  [--default-postage <lamports>] \
  [--domain <domain>] \
  [--no-ipfs] \
  [--for <address>] \
  [--skip-preflight]

Before running it you need a Solana wallet — see CLI Quickstart — and, if you’re naming a domain, that domain must already be registered and active on-chain; creation refuses an unregistered or deactivated name. A wallet has exactly one mailbox, and a mailbox names exactly one domain (switch it later with mailbox update --domain).

No encryption setup is required: mail servers seal mail straight to your wallet address, and your wallet keypair file decrypts it. Only wallets that cannot expose a decryption key (hardware and browser wallets, which can only sign) need to publish a delegated encryption key.

Arguments

• --keypair <path> (optional) — the mailbox owner’s keypair. Defaults to the keypair in your Solana CLI config when omitted.
• --default-postage <lamports> (optional) — the starting default postage for the mailbox, in lamports. Defaults to 1 SOL worth of lamports; set it high to price out spam, then lower it per-sender by adjusting a frombox’s stamp price.
• --domain <domain> (optional) — the domain that can send mail to this mailbox, by name (e.g. sithbit.com) or by its account address. Defaults to sithbit.com when omitted.
• --no-ipfs (optional) — a bare flag; present opts the mailbox out of public IPFS body storage from the start, absent leaves it off (the default). See Opting out of IPFS storage.
• --for <address> (optional) — create the mailbox for a different owner (a base58 wallet address): a sponsored create, see below. Requires --domain, and the fee payer must be that domain’s on-chain authority.
• --skip-preflight (optional) — submits the transaction without a local simulation pass first.

Sponsored creation (--for)

A domain’s on-chain authority can provision mailboxes for other wallets under its domain — see Sponsored mailboxes for the concept and its guards. With --for, the fee payer funds the mailbox but the named address owns it:

• The payer must be the on-chain authority of the --domain domain; anyone else is refused (UnauthorizedDomainSponsor, error 96). Omitting --domain is refused client-side, and a raw instruction without a domain fails on-chain (SponsoredMailboxRequiresDomain, error 95).
• Any --default-postage you pass is overridden to the 1-SOL spam floor on-chain.
• The self-alias is not bundled — the owner claims their own alias.
• The payer is recorded as the mailbox’s funder: closing the mailbox refunds its rent to the payer, not the owner.

Examples

Create a mailbox with an explicit postage and domain:

sithbit mailbox create \
  --default-postage 100000 \
  --domain sithbit.com \
  --keypair <path to wallet keypair>

Create a mailbox that opts out of public IPFS storage from the start:

sithbit mailbox create \
  --domain sithbit.com \
  --no-ipfs \
  --keypair <path to wallet keypair>

As a domain’s authority, sponsor a mailbox for one of your users (the postage you’d pass is forced to the 1-SOL floor either way):

sithbit mailbox create \
  --for <user wallet address> \
  --domain example.com \
  --keypair <path to the domain authority's keypair>

Related commands

• Looking up a mailbox — inspect a mailbox’s settings, including whether it opted out of IPFS.
• Update a mailbox — change postage, domain, or the no-IPFS flag on a mailbox that already exists.
• Mailbox keys — publish a delegated encryption key for signing-only wallets.