pp-multimail

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/social-and-messaging/multimail/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# MultiMail — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `multimail-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install multimail --cli-only
   ```
2. Verify: `multimail-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/social-and-messaging/multimail/cmd/multimail-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## When to Use This CLI

Use multimail-pp-cli when you need to manage an agent email fleet — process oversight queues, monitor trust ladder progression, search across mailboxes, and track inbox health. It turns MultiMail's graduated autonomy model into a daily operator workflow.

## Anti-triggers

Do not use this CLI for:
- Sending bulk marketing email — MultiMail is for agent-to-human communication, not mass email
- Managing non-MultiMail email accounts (Gmail, Outlook) — use better-email-mcp or native MCP tools
- Real-time email streaming — use MultiMail webhooks directly for sub-second event delivery
- Account billing changes — use the MultiMail dashboard for payment and plan management

## Unique Capabilities

These capabilities aren't available in any other tool for this API.

### Agent-native plumbing
- **`fleet health`** — Single-command account-wide health snapshot: mailbox count, oversight queue depth, webhook delivery rate, domain verification status, usage vs plan limits.

  _When an agent needs to know if its MultiMail integration is healthy before sending, one command replaces checking 5 separate endpoints._

  ```bash
  multimail-pp-cli fleet health --json --agent --select mailboxes.total,oversight.pending_count,webhooks.success_rate
  ```
- **`oversight bulk-decide`** — Approve or reject all pending emails matching a filter (by mailbox, sender, or age) in one command.

  _When an agent's test queue has 20 pending emails, one command clears them instead of 20 individual approve calls._

  ```bash
  multimail-pp-cli oversight bulk-decide --approve --mailbox support-agent --json
  ```
- **`oversight velocity`** — See approval/rejection rates and median decision latency per mailbox across your entire fleet.

  _When an agent's sends are stuck in approval queues, this pinpoints which mailbox's operator is the bottleneck._

  ```bash
  multimail-pp-cli oversight velocity --json --days 7
  ```
- **`trust status`** — Fleet-wide view of each mailbox's oversight mode, time-at-level, and upgrade eligibility.

  _Before requesting a trust upgrade, an agent should know which mailboxes are ready and which have been at their current level longest._

  ```bash
  multimail-pp-cli trust status --json --agent --select name,oversight_mode,time_at_level
  ```
- **`trust timeline`** — Per-mailbox chronological history of every oversight mode change with timestamps and who triggered it.

  _When evaluating whether to request a trust upgrade, an agent needs to show its history of responsible operation at each level._

  ```bash
  multimail-pp-cli trust timeline --mailbox support-agent --json
  ```
- **`emails send-and-wait`** — Send an email and block until a reply arrives or timeout — the agent test loop in one command.

  _When an agent needs to send and process the reply in one workflow step, this replaces a manual send-poll-read loop._

  ```bash
  multimail-pp-cli emails send-and-wait --mailbox test-agent --to [email protected] --subject 'Test' --body 'Hello' --timeout 5m --json
  ```

### Local state that compounds
- **`mailboxes allowlist coverage`** — See what percentage of recent recipients are covered by allowlist patterns vs gated.

  _Before adding allowlist entries, an agent should know which recipients are already covered and which cause the most gating friction._

  ```bash
  multimail-pp-cli mailboxes allowlist coverage --mailbox primary --days 30 --json --agent --select pattern,match_count,percentage
  ```
- **`inbox health`** — Per-mailbox health snapshot: unread count, oldest unread age, reply rate, and thread depth.

  _An agent monitoring its own inbox health can detect when it is falling behind on replies before the operator notices._

  ```bash
  multimail-pp-cli inbox health --json --agent --select mailbox,unread_count,oldest_unread_age,reply_rate
  ```
- **`threads stale`** — List conversation threads with no reply in N days — surfaces dropped conversations.

  _A dropped conversation thread is a customer-facing failure; this is the agent's early warning system._

  ```bash
  multimail-pp-cli threads stale --days 3 --json --agent --select thread_id,subject,last_reply_age,mailbox
  ```
- **`audit compliance`** — Cross-entity compliance report: oversight bypass count, approval/rejection counts, decision latency percentiles per mailbox.

  _When an auditor needs to verify that agents operated within their approved trust levels, this replaces manual log correlation._

  ```bash
  multimail-pp-cli audit compliance --days 30 --json
  ```
- **`webhooks health`** — Per-webhook success rate, failure count, last delivery timestamp, and consecutive failure streak.

  _When an agent's real-time event pipeline depends on webhooks, this surfaces delivery health before silent failures accumulate._

  ```bash
  multimail-pp-cli webhooks health --json --agent --select webhook_id,url,success_rate,consecutive_failures
  ```

## Command Reference

**account** — Manage account

- `multimail-pp-cli account create` — Requires a solved proof-of-work challenge. Creates a pending signup and sends a confirmation email.
- `multimail-pp-cli account create-challenge` — Returns an ALTCHA challenge. Solve it and include the solution as pow_solution in POST /v1/account.
- `multimail-pp-cli account create-resendconfirmation` — Public endpoint (no auth required). Resends the activation email with a new code for unconfirmed accounts.
- `multimail-pp-cli account delete` — Hard-deletes all tenant data (mailboxes, emails, API keys, usage, audit log). Frees the slug for re-registration.
- `multimail-pp-cli account list` — Get current tenant info and usage
- `multimail-pp-cli account update` — Update tenant settings

**admin** — Manage admin

- `multimail-pp-cli admin` — Admin-only. Creates a new API key and emails it to the tenant's oversight email.

**agent** — Manage agent

- `multimail-pp-cli agent create` — Initiates agent registration using verified_email identity assertion.
- `multimail-pp-cli agent create-auth` — Completes the auth.md registration by validating the claim_token and OTP.
- `multimail-pp-cli agent list` — Human-facing page that displays the 6-digit OTP for agent registration. Linked from the verification email.

**api-keys** — Manage api keys

- `multimail-pp-cli api-keys create` — Requires admin scope. The raw key is returned only once in the response.
- `multimail-pp-cli api-keys delete` — Requires admin scope. Returns 202 with pending_approval on first call; resend with approval_code to complete.
- `multimail-pp-cli api-keys li