Email

This section covers the mechanics of the mail operations themselves — sending, getting, pinning, and deleting a message, plus the reply-bounty incentive that rides on top of a send — as they happen against the chain and IPFS. In everyday use your mail client performs these for you; this page is for understanding exactly what happens underneath.¹ See Addresses for how wallet addresses double as email addresses, and Economics for the money side.

The split model: body off-chain, envelope on-chain

A SithBit message is deliberately split in two so that nothing sensitive and nothing large ever touches the chain:

• The body lives on IPFS. The message body (headers, subject, and text) is sealed to the recipient’s encryption key and pinned to IPFS as an opaque blob. It is content-addressed: the blob’s hash is its address, its content identifier (CID).
• The envelope lives on-chain. Only a small envelope goes on-chain as a SendMail instruction — the sender, the recipient, a timestamp, and that CID. The chain never sees the plaintext, and never stores more than a hash and a pointer, so on-chain cost stays flat no matter how large the mail is.

Because the CID is a hash of the sealed bytes, the two halves are tamper-evident against each other: given the on-chain CID, anyone fetching the body from any IPFS source can hash what they got and confirm it is exactly the body the sender committed to. Nothing else can hash to that CID.

The lifecycle of a message

The end-to-end path, from a sealed compose to the settling delete:

1. Send — seals the body, pins it to IPFS, and writes the envelope (with its CID) on-chain via SendMail. Postage — the frombox price for that sender, or the mailbox default — gates whether the send is allowed at all, and the postage the sender pays funds the new message account.
2. Get — reads the on-chain envelope, fetches the sealed body from IPFS by its CID, and decrypts it with the recipient’s wallet (or a delegated key).
3. Pin — re-pins a verified body to a pinning provider the recipient controls, so a message stays retrievable even if the operator that originally pinned it stops.
4. Delete — settles the message: it pays the postage out (to the recipient, with a share to the domain operator), refunds the prepaid fees, and reaps the on-chain message account so its rent is returned.

Deletion is the settlement trigger, not just a cleanup step — a message account holds the sender’s postage until it is deleted. See Deleting mail and Economics for the exact split.

Note: in normal operation, MX/SMTP servers and your mail client handle sending and receiving mail for you — see Running a mail server. The operations documented here talk to the chain and IPFS directly, which is useful for testing, scripting, or understanding exactly what a mail server does on your behalf.

Sending mail

The send operation records a delivery on-chain: it burns one stamp from the sender’s frombox and writes a new message account for the recipient pointing at the body’s IPFS CID. It does not move any bytes around — the encrypted body must already exist on IPFS. This is the low-level primitive an MX server runs on the sender’s behalf after it has sealed and pinned an incoming message; end users normally send through an ordinary mail client, not this command.

Want a faster answer? Attach a reply bounty and put SOL behind your question — the recipient collects it the moment they reply, no separate escrow to set up. See Reply bounties for the full mechanics.

See Sending mail for the full command reference, its preconditions, and what reaches the chain.²

Reading mail

The get operation is the receive side of send: it reads a mailbox’s message accounts from the chain, prints their on-chain listing, and — when a body is fetched — pulls the encrypted bytes from an IPFS gateway and (optionally) decrypts them with your key. It is the primitive an IMAP/ POP server runs to materialize a mailbox; end users normally read mail through an ordinary client rather than this command. Reading is read-only: a get never signs a transaction and never settles postage — that is delete’s job.

See Getting mail for the full command reference, the on-chain listing format, and decrypting a fetched body separately.

Pinning to IPFS

A message body never lives on-chain — only its content identifier (CID) does. The bytes live on IPFS, pinned by whichever mail server received the message. That is convenient, but it means the availability of your own mail depends on an operator continuing to pin it. If that operator stops — or you simply want to hold your own copy — you can pin the body to a provider you control. That is what the pin operation does: it fetches each message body, proves it against the on-chain CID, and re-pins the verified bytes somewhere of your choosing, so the mail stays retrievable no matter what the operator does.

See Pinning mail for provider choices, message selection, keeping mail pinned continuously, and the verify guarantee.

Deleting mail

Deleting a message is how a received email is settled and its on-chain account reclaimed. A mail message lives on-chain as its own account — a small envelope (sender, recipient, timestamp, and the IPFS CID of the sealed body) funded with the postage the sender paid to deliver it. That account sits open until someone deletes it. Deletion is the single event that pays the postage out, refunds the prepaid transaction fees, and closes (reaps) the message account so its rent is returned rather than left locked on-chain forever.

See Deleting mail for who may delete, the exact settlement order, and the delete-vs-refund distinction.

Reply bounties

A reply bounty turns postage’s pay-for-attention into pay-for-an-answer: the sender escrows extra lamports on the message itself, and the recipient collects them by replying before a deadline. No reply by the deadline and the sender takes the money back. The bounty rides the message account — there is no separate escrow account to create, fund, or clean up.

Attach a bounty from the compose card in any GUI client, and claim or refund one from its Bounties pane — see Replying, and attaching a bounty.³

1. The sithbit CLI drives each of these operations directly from the terminal; each section below links its full command reference. ↩

2. End users normally never run these commands — an ordinary mail client and its MX server perform the same operations on your behalf. ↩

3. From the terminal: Reply bounties covers attaching, linking a reply, and claiming or refunding. ↩