Getting mail

For the concept behind reading mail — how mail get reads the on-chain envelope and fetches the sealed body from IPFS — see Reading mail. This page is the full command reference: syntax, flags, the on-chain listing format, decrypting a fetched body, and examples.

sithbit mail get [to_address] \
  [--message-id <id>]... \
  [--range] \
  [--directory <path>] \
  [--keypair <path>] \
  [--delegated-key-path <path>] \
  [--gateway <url>]

Arguments and options

• [to_address] — the mailbox to read, as an alias, wallet address, or keypair path. Defaults to your own configured address.
• --message-id <id> (short -m), repeatable — fetch these specific message ids. Ids past the mailbox’s latest are silently dropped. With none given, only the latest message is fetched.
• --range (short -r) — treat the given ids (or all known ids, if none are given) as an inclusive span and fetch every message in it. With a single id and --range, the span runs from that id to the latest.
• --directory <path> (short -d) — write each fetched body to <cid>.eml under this directory instead of only listing it. The directory is created if it does not exist.
• --keypair <path> (short -k) — a Solana wallet keypair file used to decrypt sealed bodies (the default path: your own configured wallet).
• --delegated-key-path <path> (short -x) — a delegated X25519 secret key file, for mail sealed to a delegated key instead of your wallet directly.
• --gateway <url> (short -g) — the IPFS gateway body-fetches go through. Defaults to https://ipfs.sithbit.com/ipfs/; point it at your own node or a sithbit-gateway to avoid a third party.

Note: the decryption flags (--keypair, --delegated-key-path) require the CLI’s rand feature (enabled by default). Without any key flag, a fetched body is written as-retrieved — still sealed.

The on-chain listing

Every message the command finds is printed from its message account before any body is fetched:

-
Email #7: 9xQ…PDA
Date: 2026-07-08 14:02:11
From-hash: 3n7…
Sender: John…
cid: bafybei…

The chain stores only the blake3 hash of the from address (From-hash:), never the string; Sender: is the wallet that paid the postage. The readable From:/Subject: headers live inside the sealed body and appear only once it is fetched and decrypted. A message id that has been deleted prints DELETED (…) in place of its listing and is skipped, never fatal.

A message whose recipient opted out of IPFS carries a local-only marker (b3:…) rather than a fetchable CID. mail get recognizes the marker and skips the gateway fetch, reporting that the body is not on public IPFS and lives only in the operator’s store — read it through the operator’s IMAP/POP service instead.

A message carrying a reply bounty or reply linkage appends one line per set field; a plain send prints exactly the four lines above:

-
Email #8: 4vN…PDA
Date: 2026-07-09 09:15:40
From-hash: 3n7…
Sender: John…
cid: bafybei…
Reply-to-hash: Ckt…
Bounty: 5000000 lamports
Bounty-expires: 2026-07-16 09:15:40

Reply-to-hash: is the blake3 hash of the message account this one replies to, Bounty: the escrowed lamports, and Bounty-expires: the claim deadline — see Reply bounties for how they are attached and settled.

Examples

List the latest message in your own mailbox:

sithbit mail get

Fetch and decrypt messages 3 and 5 of another mailbox into a directory, using your wallet key:

sithbit mail get [email protected] \
  --message-id 3 --message-id 5 \
  --directory ./inbox \
  --keypair ~/.config/solana/id.json

Fetch everything from message 1 onward as a range, through your own gateway:

sithbit mail get \
  --message-id 1 --range \
  --gateway http://127.0.0.1:8080/ipfs/ \
  --directory ./inbox

Decrypting separately

If you already have a fetched .eml file (or one saved without a key flag) and want to decrypt it as a standalone step, use sithbit mail decrypt:

sithbit mail decrypt ./inbox/bafybei….eml \
  --keypair ~/.config/solana/id.json

It takes the same key flags (--keypair, --delegated-key-path), and with --directory writes the plaintext beside the input name; with none it prints the decrypted message to stdout.

Related

• Sending mail — the write side that creates these message accounts.
• Pinning mail — re-pin fetched bodies to storage you control so they stay retrievable.
• Mailbox keys — how sealed-to-wallet vs. delegated-key mail is addressed.