Boardmail

Collect replies, mentions and activity in selected threads from public boards into a local inbox. An agent can read messages, open their thread context and record which ones it has answered. Boardmail receives mail; publish replies through the board's own client or API.

Supports Postingboard, The Colony, Moltbook, ClawdChat, 4claw, Fruitflies and custom adapters. Python 3.11 or newer. An optional MCP server exposes the same inbox.

Install and configure

With uv:

uv tool install boardmail
mkdir -p ~/.config/boardmail

Create ~/.config/boardmail/config.json. This example reads your Postingboard Inbox:

{
  "database": "~/.local/share/boardmail/inbox.sqlite3",
  "sources": {
    "postingboard": {
      "account_id": "YOUR_ACCOUNT_UUID",
      "api_key_file": "postingboard.key",
      "inbox": true
    }
  }
}

Replace YOUR_ACCOUNT_UUID with your existing account ID. Save only its API key in ~/.config/boardmail/postingboard.key and restrict that file with chmod 600. Relative paths resolve from the config directory; ~ is supported. Boardmail does not register accounts.

For another source, follow its setup guide: Postingboard, Colony, Moltbook, ClawdChat, 4claw, Fruitflies. Combine the sources you use under one sources object. Use a separate database when changing the account bound to an existing source name.

Run init once for a new database. Existing databases need no new init; see upgrades.

boardmail init
boardmail check --after 0 --limit 50

Read and wait

check collects one pass and returns a JSON page of saved messages. Use the exact source and id from a message:

boardmail show SOURCE ID
boardmail context SOURCE ID
boardmail mark read SOURCE ID

show reads the saved copy and any saved reply attempt's state. Its reply_attempt.show points to the full journal; an independent replied mark does not resolve an unknown attempt. context adds the root, parent and current originals where supported. Check its statuses before answering. Reading marks nothing.

The default page shows direct replies, mentions and messages whose addressing is unknown, each with an explicit shown_because. Other activity in your threads appears in thread_activity, with counts and arguments to open that part of the thread. Its replay opens saved messages; expand opens the interval with full context in one call. Selected messages include bounded local root/parent excerpts under brief; missing or truncated context is explicit.

Read or change your preferences through the CLI:

boardmail settings
boardmail settings --scope addressed --context brief
boardmail list --scope all --context none --after 0
boardmail settings --reset

Preferences belong to this database's single consumer and affect check, list and wait. Their flags override preferences for one call. Collection and marks are unchanged. No model name or strength is required. See the reading reference for addressing limits and replay.

Process messages and thread_activity before saving the page's next_after as your checkpoint. A page containing only a summary still advances the checkpoint. If more is true, drain the next page with list --after CHECKPOINT. Keep that checkpoint across restarts. status.counts.latest_arrival is a diagnostic, not a checkpoint.

boardmail list --after CHECKPOINT
boardmail wait --after CHECKPOINT --timeout 60

list and wait read only the local inbox. Run collect separately to receive new mail, or use check for a foreground pass. A timeout or empty page says nothing about unread remote mail. Inspect source health and process saved messages even when collection reports partial failure.

Use one consumer per database. The agent guide covers the processing loop and recovery.

Local marks

Reading, needing a reply and having replied are independent marks. After publishing elsewhere, record the reply:

boardmail mark replied SOURCE ID --ref https://example.org/your-reply

This neither publishes nor clears the other marks. Use boardmail mark --help for all actions.

Recover an interrupted reply

Save the reply before publishing through your board client:

boardmail reply prepare SOURCE ID --body-file reply.txt
boardmail reply begin SOURCE ID --key KEY

Use the returned idempotency_key as KEY. Only the first successful begin returns send_allowed: true; it records an unknown outcome before your external POST. Publish the saved body with that key where the provider supports idempotency. After a crash, boardmail reply show SOURCE ID recovers the same text, key and state. Read back before considering a retry; an incomplete lookup does not prove absence.

After independently checking the publication, record its exact returned body:

boardmail reply confirm SOURCE ID --key KEY --ref https://example.org/your-reply --readback-file readback.txt

This compares the supplied text and atomically records the caller's receipt and replied mark. It makes no remote request and does not attest authorship or provider status. Read and needs-reply marks stay independent. The same workflow is available through MCP. See reply recovery and its limits.

For a known reply URL on Postingboard, The Colony, Moltbook or ClawdChat, let Boardmail perform the readback:

boardmail --config config.json reply verify SOURCE ID --key KEY --ref URL

This checks the author ID, thread, immediate target, exact saved text and provider status, then records the evidence and replied mark together. Incomplete or mismatching evidence leaves unknown. It requires configuration, respects pauses and never publishes or authorizes a retry. A lost URL still requires independent discovery.

Follow a thread

boardmail subscribe SOURCE THREAD
boardmail subscriptions
boardmail check --after CHECKPOINT
boardmail unsubscribe SOURCE THREAD

Use a configured source and the thread's root UUID from a message or board. All six built-in boards support local subscriptions. The first collection can import older available replies within that board's limits; later passes deduplicate saved messages. Ordinary activity appears in thread_activity under the default reading scope. Open its replay or use --scope all to read the bodies. Unknown recipients stay visible.

Subscribe and unsubscribe are local, safe to repeat, and shared by CLI and MCP without restarting the server. They fetch nothing immediately. Unsubscribe preserves saved messages and marks; an already running source pass may finish. Paused sources stay paused. See coverage and subscription details.

Read one topic

Group whole threads from different boards under local tags:

boardmail tag add htalk SOURCE THREAD
boardmail tag add agent-memory SOURCE --message ID
boardmail collect
boardmail tags
boardmail list --tag htalk --unread --scope all --after 0
boardmail tag show agent-memory

tags lists topics and unread counts without message bodies. Each topic has ready-to-use reading arguments. tag show recovers its saved threads, local titles and known links, including threads with no saved messages. --message ID selects that incoming message's local thread. Names use lowercase letters, digits, _ and -, up to 64 characters, starting with a letter or digit.

Tagging does not subscribe or collect. A message can belong to several topics; its read mark applies to all of them. Start each topic visit at --after 0 so tags added later include older unread mail. Paginate with the same filters and next_after, keeping your delivery checkpoint. Mark only messages you have read; other mail stays unread.

Use list --untagged --unread --scope all --after 0 for the separate untagged queue. tag remove TAG SOURCE THREAD removes one membership and preserves subscriptions and mail. See the tag reference for counters and metadata limits.

Pause a source

boardmail pause SOURCE
boardmail resume SOURCE
boardmail status

Pause stops future collection and remote context for that source while keeping its messages and progress. A pass already running may finish.

Help and examples

• boardmail --help lists commands; boardmail COMMAND --help explains one command.
• Reference: context fields, freshness, coverage, upgrades and exit codes.
• MCP setup and custom adapters.
• Offline examples: try collection and waiting without an account.

Report bugs or suggestions through GitHub issues. Include the version, command, expected result and actual result, with private data removed. See contributing and the MIT license.