Pp Multimail

<!-- 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:

   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.6 or newer):

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.

  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.

  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.

  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.

  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.

  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.

  multimail-pp-cli emails send-and-wait --mailbox test-agent --to user@example.com --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.

  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.

  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.

  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.

  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.

  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 list — Requires admin scope. Returns key prefix, scopes, and metadata.
• multimail-pp-cli api-keys update — Update API key name or scopes

approve — Manage approve

• multimail-pp-cli approve create — Process approval/rejection from hosted page
• multimail-pp-cli approve get — Render hosted approval page for oversight decisions

audit-log — Manage audit log

• multimail-pp-cli audit-log — Returns audit log entries with cursor pagination. Requires admin scope.

auth-md — Manage auth md

• multimail-pp-cli auth-md — Returns a markdown document describing MultiMail's agent registration flow, trust ladder, and scope model.

billing — Manage billing

• multimail-pp-cli billing create — Requires admin scope.
• multimail-pp-cli billing create-checkout — Create a Stripe checkout session for plan upgrade
• multimail-pp-cli billing create-coinbasewebhook — Coinbase Commerce webhook handler (public, signature-verified)
• multimail-pp-cli billing create-cryptocheckout — Create a Coinbase Commerce checkout (crypto payment)
• multimail-pp-cli billing create-portal — Requires admin scope.
• multimail-pp-cli billing create-pricingcheckout — Creates an inactive tenant, provisions a default mailbox, and returns a Stripe checkout URL.
• multimail-pp-cli billing create-stripewebhook — Stripe webhook handler (public, signature-verified)
• multimail-pp-cli billing list — Public endpoint. Returns the API key stored during pricing-checkout, then deletes it.

confirm — Manage confirm

• multimail-pp-cli confirm create — JSON response includes: status, name, oversight_mode, api_key, mailbox_id, mailbox_address, oversight_email, use_case.
• multimail-pp-cli confirm get — Redirect to frontend confirmation page with code prefilled
• multimail-pp-cli confirm list — Redirect to frontend confirmation page at multimail.dev/confirm

contacts — Manage contacts

• multimail-pp-cli contacts create — Add a contact to the address book. Requires send scope.
• multimail-pp-cli contacts delete — Requires admin scope.
• multimail-pp-cli contacts list — Search address book by name or email. Omit query to list all. Requires read scope.

data_export — Manage data export

• multimail-pp-cli data-export — Requires admin scope. Rate limited to 1 request per hour.

domains — Manage domains

• multimail-pp-cli domains create — Add a custom domain (Pro/Scale only)
• multimail-pp-cli domains delete — Delete a custom domain
• multimail-pp-cli domains get — Get custom domain detail
• multimail-pp-cli domains list — Requires admin scope.

emails — Manage emails

• multimail-pp-cli emails — Requires read scope.

funnel — Manage funnel

• multimail-pp-cli funnel — Pricing page beacon hit via navigator.sendBeacon to track open/submit/error events on the signup modal.

health — Manage health

• multimail-pp-cli health — Verifies D1 and R2 connectivity. No auth required.

mailboxes — Manage mailboxes

• multimail-pp-cli mailboxes create — Requires admin scope.
• multimail-pp-cli mailboxes delete — Requires admin scope.
• multimail-pp-cli mailboxes list — Requires read scope.
• multimail-pp-cli mailboxes update — Requires admin scope. Oversight mode can only be downgraded here; upgrades require the upgrade flow.

operator — Manage operator

• multimail-pp-cli operator create — Requires admin scope. Clears the operator-session cookie.
• multimail-pp-cli operator create-startsession — Requires admin scope. Sends a one-time code to the oversight email and begins the operator-session OTP flow.
• multimail-pp-cli operator create-verifysession — Requires admin scope. Exchanges a one-time code for a short-lived HttpOnly operator-session cookie.
• multimail-pp-cli operator list — Requires admin scope. Reports whether the current browser has an active operator-session cookie.

oversight — Manage oversight

• multimail-pp-cli oversight create — Requires oversight scope. Approved outbound emails are sent immediately.
• multimail-pp-cli oversight list — List emails pending oversight approval

slug-check — Manage slug check

• multimail-pp-cli slug-check <slug> — Check if a slug is available for registration. Returns suggestions if taken or reserved. No auth required.

support — Manage support

• multimail-pp-cli support — Public endpoint. Requires a solved ALTCHA proof-of-work payload. Sends a message to support@multimail.dev.

suppression — Manage suppression

• multimail-pp-cli suppression delete — Allows future emails to be sent to this address again. Requires admin scope.
• multimail-pp-cli suppression list — Returns addresses suppressed due to bounces, spam complaints, or manual unsubscribes. Requires admin scope.

unsubscribe — Manage unsubscribe

• multimail-pp-cli unsubscribe create — Process unsubscribe request
• multimail-pp-cli unsubscribe get — Render unsubscribe page (CAN-SPAM)

usage — Manage usage

• multimail-pp-cli usage — Requires read scope. Returns usage counts for the current billing period.

webhook-deliveries — Manage webhook deliveries

• multimail-pp-cli webhook-deliveries — Returns recent webhook delivery attempts. Requires admin scope.

webhooks — Manage webhooks

• multimail-pp-cli webhooks create — Subscribe to email events. Returns the signing secret (shown only on creation). Requires admin scope.
• multimail-pp-cli webhooks create-postmark — Postmark bounce/complaint/delivery webhook handler
• multimail-pp-cli webhooks create-postmarkinbound — Receives inbound emails from Postmark. Authenticated via HTTP Basic Auth with the Postmark webhook secret.
• multimail-pp-cli webhooks delete — Delete a webhook subscription
• multimail-pp-cli webhooks get — Includes signing secret. Requires admin scope.
• multimail-pp-cli webhooks list — Requires admin scope. Signing secrets are not included in the list.

well-known — Manage well known

• multimail-pp-cli well-known get — Rate-limited to 10 lookups per IP per hour.
• multimail-pp-cli well-known list — Returns the ECDSA P-256 public key used to sign X-MultiMail-Identity headers.
• multimail-pp-cli well-known list-wellknown — Returns OAuth authorization server metadata with an agent_auth extension block describing the auth.
• multimail-pp-cli well-known list-wellknown-2 — Returns metadata about MultiMail as an OAuth-protected resource, including supported scopes and authorization servers.