Sending mail

For the concept behind sending mail — the split on-chain/off-chain model, what SendMail records, and how postage gates a send — see Sending mail. This page is the full command reference: syntax, flags, preconditions, and examples.

sithbit mail send <to> \
  [--from <address>] \
  (--cid <cid> | --path <file>) \
  [--keypair <keypair>] \
  [--skip-preflight] \
  [--bounty <lamports>] [--bounty-window <seconds>] [--reply-to <address>]

Arguments and options

• <to> — the recipient, as an alias, wallet address, or keypair path. Required. The recipient must already have a mailbox; the message account is a PDA seeded on that wallet and the next message id.
• --from <address> (short -f) — the From: address, which selects which frombox is charged. Defaults to the sending keypair’s own address.
• --cid <cid> (short -c) — the IPFS CID of a body that is already pinned somewhere. You supply the known CID directly.
• --path <file> (short -p) — a local file whose CID is computed from its bytes. Exactly one of --cid or --path is required, and they are mutually exclusive.
• --keypair <keypair> (short -k) — the sender’s signing keypair. Defaults to the Solana CLI’s configured wallet (~/.config/solana/cli/config.yml). This wallet pays the stamp and signs the transaction.
• --skip-preflight (short -s) — submit without the RPC pre-flight simulation. Off by default; see the appendix for when skipping helps and what it costs.
• --bounty <lamports> — escrows a reply bounty on the message; see Reply bounties for how claiming and refunding work. Omit for a plain send.
• --bounty-window <seconds> — how long the recipient has to reply and claim; only meaningful with --bounty. See Reply bounties.
• --reply-to <address> — links this send as a reply to an earlier message (the bountied message’s account address), making it eligible to claim that message’s bounty. See Reply bounties.

Important: --path only computes the local file’s IPFS content identifier (CID) from its bytes — it does not upload or pin the content anywhere. Before the recipient can actually fetch and decrypt the message, the file must be separately pinned to IPFS (for example, through the embedded node in your own sithbitd, or a shared sithbit-ipfsd). --cid is for content that’s already pinned somewhere — you supply its known CID directly instead of a local file.

Examples

Send a locally-prepared .eml file, computing its CID on the way:

sithbit mail send [email protected] \
  --from [email protected] \
  --path ./message.eml

Send a body you have already pinned, referencing it by CID:

sithbit mail send [email protected] \
  --cid bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

On success the command prints the assigned message id, the CID, and the From/To pair, followed by the transaction URL:

Sent message #7 bafybei… <From:[email protected] To:[email protected]>
https://explorer.solana.com/tx/…

Before you send

Two preconditions must hold or the transaction is rejected on-chain:

• The frombox must exist and hold at least one stamp. The <from> → <to> frombox is charged one stamp per send (see Add stamps for what a stamp is worth and how to top one up). A missing or empty frombox fails the send; new/unknown fromboxes also inherit a deliberately high default price to price out spam.
• The recipient must have a mailbox. The message account seeds on the recipient wallet, and its id is the mailbox’s current message count plus one — so the mailbox must exist for the id to be assigned.
• The recipient must not have opted out of IPFS. If the recipient’s mailbox has the no_ipfs opt-out set, mail send refuses before touching the CID: this command pins the body client-side with no operator store behind it, so it cannot honor the opt-out the way SMTP delivery does. Deliver through an ordinary mail client (SMTP) instead, and the recipient’s operator stores the copy privately.

What reaches the chain

Neither address string reaches the chain: the instruction carries only blake3 hash of the normalized --from address (the frombox seed), and the recipient is identified by the wallet the message account’s PDA seeds on. The readable From:/To: headers travel solely inside the sealed body — see the threat model for exactly what an observer can and cannot learn.

Related

• Getting mail — the receive side; fetch and decrypt what was sent here.
• Pinning mail — keep a body retrievable on infrastructure you control.
• Delete mail — settle a delivered message’s postage once it has been read.
• Reply bounties — attach an escrowed reward to a send and claim it on reply.