Deleting mail

For the concept behind deleting mail — why deletion is the settlement trigger for a message’s prepaid postage — see Deleting mail. This page is the full command reference: syntax, flags, who may delete, the exact settlement order, examples, and delete vs. refund.

sithbit mail delete <message_id> \
  [to_address] \
  [--keypair <keypair>] \
  [--skip-preflight]

• <message_id> — the numeric id of the message to delete (the same id shown by sithbit mail get). Required.
• to_address — the recipient whose mailbox the message belongs to. Defaults to your own address; pass an alias, wallet address, or keypair path to name someone else’s mailbox (the message PDA is seeded on the recipient, so this selects which message #<id> is meant).
• --keypair <keypair> (short -k) — the signing keypair, defaulting to the CLI’s configured wallet.
• --skip-preflight (short -s) — skip the RPC pre-flight simulation and submit the transaction directly.

Who may delete

Either party to the message may delete it: the on-chain program requires the signer to be either the sender or the recipient of the message, and rejects anyone else. In normal operation it is the recipient (or the MX server acting on their behalf) who deletes, because deletion is what pays the postage into the recipient’s wallet.

Example

sithbit mail delete 3

deletes message #3 from your own mailbox and prints the resolved sender plus the settling transaction:

Found sender address 7Xh…q4M
Deleted message #3 for 9aF…2kD
https://explorer.solana.com/tx/5Jm…8sT

To delete a message in someone else’s mailbox (for instance an operator settling on a user’s behalf), name the recipient:

sithbit mail delete 3 [email protected] --keypair operator.json

What happens on-chain

The command builds a DeleteMail instruction carrying nine accounts: the signing payer, the message’s sender and recipient, the system program, the message account itself, and the recipient’s settlement accounts (their mailbox, its domain, that domain’s authority, and the postoffice). The program then drains the message account’s whole balance and closes it, in this order:

1. Sender refund. The sender recovers the message account’s rent plus the fee for their original SendMail signature (both were prefunded by the stamp surcharge the sender paid at purchase).
2. Deleter refund. The signer submitting this delete recovers this transaction’s signature fee — also prefunded — so settling costs the deleter nothing net.
3. Operator share. If the recipient’s mailbox names an active domain, that domain’s authority (the MX operator) collects 10% of the remaining postage. The share lapses to zero when the chain legitimately doesn’t resolve — no mailbox, no domain set, or the domain is closed or inactive — but a named, active domain must be presented with the correct authority account or the instruction is rejected, so a deleter can’t cheat the operator out of its cut with filler accounts.
4. Recipient postage. The recipient collects everything left, rounded down to the protocol’s settlement quantum (1000 lamports). This is the actual pay-for-attention the postage model exists to deliver.
5. Rounding residue. The sub-quantum remainder accrues to the postoffice (the postmaster’s operating revenue at scale).

Once the balance reaches zero the message account is reaped — the id is gone and a later get for it returns nothing. See Economics for the full postage/settlement model and the exact split.

Delete vs. refund. Deletion settles postage to the recipient. There is a sibling command, sithbit mail refund <message_id>, for the opposite outcome: the recipient (and only the recipient) refuses the mail and returns the postage to the sender instead of keeping it. Refund reuses the same nine-account shape and likewise reaps the message account and refunds the prepaid fees, but pays no postage to the recipient and no operator share. Use delete to accept and settle; use refund to reject.