Pinning mail

For the concept behind pinning — why a message body’s availability depends on an operator, and how re-pinning to a provider you control fixes that — see Pinning to IPFS. This page is the full command reference: provider choices, message selection, keeping mail pinned continuously, the verify guarantee, and examples.

sithbit mail pin [to_address] \
  [--message-id <id>]... \
  [--range] \
  [--gateway <url>] \
  --provider (pinata | filebase | remote) \
  [provider credential flags] \
  [--watch <seconds>]

to_address defaults to your own address; give an alias, wallet address, or keypair path to pin someone else’s mailbox instead (you still need the provider credentials, since the pin lands on your provider).

Re-pinning puts a copy on infrastructure you run. To instead pay the recipient’s operator to keep their pin past the default retention window, see pinning leases — the two compose.

Choosing messages

Message selection mirrors sithbit mail get exactly:

• No --message-id — pins the latest message only.
• --message-id <id> (short -m), repeatable — pins those specific ids.
• --range (short -r) — treats the given ids (or all known ids, if none are given) as an inclusive range and pins every message in the span.

A message that has been deleted or is otherwise unavailable is reported and skipped, never fatal — the rest of the batch still pins. A message whose recipient opted out of IPFS carries a local-only marker (b3:…) instead of a fetchable CID: there is nothing on a gateway to fetch, hash-verify, or re-pin, so mail pin reports it and skips it rather than failing on a gateway 404.

Choosing a provider

--provider selects where the verified bytes are stored. Because the pin lands on infrastructure the recipient controls, the credentials are passed as flags rather than read from a config file.

remote (the default)

A self-hosted sithbit-ipfsd daemon spoken to over HTTP. This is the minimal path: with no flags at all, --provider remote targets a loopback daemon and needs no credentials, so mail pin works out of the box against a node you run yourself.

• --remote-endpoint <url> — daemon endpoint (default http://127.0.0.1:8182).
• --remote-token <token> — bearer token, only if the daemon requires one.

pinata

Pinata’s hosted pinning API, authenticated with a bearer JWT.

• --pinata-jwt <jwt> — Pinata bearer JWT (required).
• --pinata-gateway <url> — gateway base URL for provider-side fetches (default https://gateway.pinata.cloud).

filebase

Filebase’s S3-compatible IPFS pinning endpoint.

• --filebase-access-key <key> — S3 access key (required).
• --filebase-secret-key <key> — S3 secret key (required).
• --filebase-bucket <bucket> — target bucket (required).
• --filebase-endpoint <url> — S3 endpoint (default https://s3.filebase.com).

Keeping mail pinned: --watch

By default mail pin runs a single pass and exits. Pass --watch <seconds> to keep it running: after the first pass it re-enumerates the mailbox and re-pins it every N seconds, so newly-arrived messages stay pinned without a manual re-run. Each tick prints a one-line summary of how many bodies were pinned and how many errored; a transient failure (an RPC blip, say) is reported and the loop continues.

Examples

Pin your latest message to a loopback sithbit-ipfsd — the zero-config path:

sithbit mail pin

Pin messages 1 through 10 of your own mailbox to Pinata:

sithbit mail pin \
  --message-id 1 --message-id 10 --range \
  --provider pinata \
  --pinata-jwt "$PINATA_JWT"

Continuously mirror an entire mailbox to Filebase, re-checking every five minutes:

sithbit mail pin \
  --range \
  --provider filebase \
  --filebase-access-key "$FILEBASE_KEY" \
  --filebase-secret-key "$FILEBASE_SECRET" \
  --filebase-bucket my-sithbit-mail \
  --watch 300

The verify guarantee

Before anything is pinned, the fetched bytes are hashed and compared against the CID recorded on-chain for that message. Only bytes that hash to the expected CID are pinned; a mismatch is refused. A gateway that serves corrupted or substituted content therefore cannot get bad data into your provider — the worst it can do is fail to serve the body, in which case that message is skipped.