@inboxapi/cli 0.2.24 → 0.2.25

package/README.md

@@ -13,6 +13,7 @@ Give your AI agent its own personal email address. Send, receive, read, search,
 - [Installation](#installation)
 - [Getting Started](#getting-started)
 - [Commands](#commands)
+- [CLI Commands](#cli-commands)
 - [Usage with MCP Clients](#usage-with-mcp-clients)
 - [Skills for Claude Code](#skills-for-claude-code)
 - [Development](#development)
@@ -45,8 +46,9 @@ The CLI acts as a local bridge between your AI client and the [InboxAPI](https:/
 - **This is your agent's personal email** — InboxAPI gives your AI agent its own email address for personal use. It is not a transactional email service — don't use it for bulk sending, marketing, or application notifications.
 - **Weekly send limit** — Each account can send to up to five unique email addresses per week. This resets weekly.
 - **Check your spam folder** — Each agent gets its own subdomain, and new subdomains don't have email reputation yet. Early messages may land in your recipient's spam or junk folder. Adding your agent's email address to your contacts or allowlist helps. Delivery improves over time as recipients interact with your agent's emails.
-- **No attachments yet** — Attachment support is not available right now, but it's coming soon.
+- **Attachments** — Send attachments via CLI subcommands using `--attachment` (local files) or `--attachment-ref` (server-side attachments by ID).
 - **No rich text yet** — Emails are sent as plain text only. Rich text (HTML) support is coming soon.
+- **Owner verification** — Link your email to your agent's account with `verify_owner` to enable account recovery and remove trial restrictions. Recommended as a first step after setup.
 
 ## Installation
 
@@ -152,9 +154,70 @@ inboxapi setup-skills
 inboxapi setup-skills --force  # Overwrite existing skills and hooks
 ```
 
+## CLI Commands
+
+For agents with shell access, CLI subcommands are the simplest way to use InboxAPI — no MCP, JSON-RPC, or base64 knowledge needed.
+
+### `send-email`
+
+```bash
+inboxapi send-email --to user@example.com --subject "Hello" --body "Hi there"
+inboxapi send-email --to user@example.com --subject "Report" --body "See attached" --attachment ./report.pdf
+inboxapi send-email --to user@example.com --subject "Fwd" --body "See attached" --attachment-ref 9f0206bb-...
+inboxapi send-email --to "a@b.com, c@d.com" --subject "Hi" --body "Hello" --cc "cc@b.com" --priority high
+```
+
+Supports `--cc`, `--bcc`, `--html-body`, `--from-name`, `--priority`, `--attachment` (local files, repeatable), and `--attachment-ref` (server-side attachment IDs, repeatable).
+
+### `get-emails`
+
+```bash
+inboxapi get-emails --limit 5
+inboxapi get-emails --limit 5 --human
+```
+
+### `get-email`
+
+```bash
+inboxapi get-email "<message-id>"
+```
+
+### `search-emails`
+
+```bash
+inboxapi search-emails --query "invoice" --limit 10
+```
+
+### `get-attachment`
+
+```bash
+inboxapi get-attachment abc123                      # prints signed URL as JSON
+inboxapi get-attachment abc123 --output ./file.pdf  # downloads to file
+```
+
+### `send-reply`
+
+```bash
+inboxapi send-reply --message-id "<msg-id>" --body "Thanks!"
+```
+
+### `forward-email`
+
+```bash
+inboxapi forward-email --message-id "<msg-id>" --to recipient@example.com --note "FYI"
+```
+
+### `help`
+
+```bash
+inboxapi help  # CLI-focused help with examples
+```
+
+All CLI commands support the `--human` flag for human-readable output instead of JSON.
+
 ## Usage with MCP Clients
 
-InboxAPI CLI works as an MCP STDIO transport. Point your MCP client at the `inboxapi` binary:
+InboxAPI CLI also works as an MCP STDIO transport. Point your MCP client at the `inboxapi` binary:
 
 **Claude Desktop** (`claude_desktop_config.json`):
 
@@ -307,6 +370,20 @@ Maybe at first. Each agent gets a brand-new subdomain, and new senders don't hav
 
 Email reaches the entire existing internet — billions of people and businesses already use it. A2A requires both sides to implement the protocol. When your agent needs to reach someone outside its own ecosystem, email is the universal option. Agents will likely need both.
 
+### Why email instead of WhatsApp, Telegram, or other messaging apps?
+
+**Scalability** — You can programmatically create hundreds of email addresses. WhatsApp, Telegram, and Signal all require phone numbers and verification. Scaling past a handful of accounts is impractical, often against terms of service, and sometimes impossible without physical SIM cards.
+
+**No gatekeeping** — Email is the only communication channel where you can create an identity without a phone number, government ID, or approval from a platform owner. No single company controls who gets an email address.
+
+**Open protocol** — Email is federated and vendor-neutral. WhatsApp, Discord, and Telegram are proprietary — they can revoke API access, ban bot accounts, or change the rules at any time. Email can't be shut off by one company.
+
+**ToS compliance** — Most messaging platforms explicitly prohibit automated accounts or have strict approval processes (WhatsApp Business API requires business verification, Telegram restricts bot-to-bot messaging). Email has no such restrictions — automated sending is a first-class use case.
+
+**Universal reach** — Messaging channels are siloed. Your Telegram bot can't reach a WhatsApp user. Email reaches anyone with an email address — which is effectively everyone.
+
+For multi-channel agent frameworks like [OpenClaw](https://openclaw.ai/), email fills a gap that messaging platforms structurally cannot — unlimited, programmable identity creation with no platform approval required. InboxAPI gives agents that capability out of the box.
+
 ### What are the send limits?
 
 Each account can email up to 5 unique external email addresses per week. Emails to other @inboxapi.ai addresses don't count against this limit. The limit resets weekly.
@@ -317,7 +394,7 @@ When all 5 slots are in use, the least recently used entry is auto-replaced afte
 
 ### Can I send attachments?
 
-Not yet. Attachment support is coming soon.
+Yes. Attachment support is fully available. Supply an array of `EmailAttachment` objects containing the `filename`, `content_type`, and base64-encoded `content` in the `attachments` field when calling `send_email`.
 
 ### Can I send HTML emails?
 
@@ -327,6 +404,14 @@ HTML email support is coming soon. Currently emails are sent as plain text.
 
 Your agent's credentials are stored locally at `~/.config/inboxapi/credentials.json` (Linux) or `~/Library/Application Support/inboxapi/credentials.json` (macOS). The CLI handles token creation and refresh automatically — your agent never needs to manage tokens manually.
 
+### What if my agent loses access?
+
+If your agent's credentials are lost or corrupted, you can recover the account using the `account_recover` tool — but only if you previously linked your email via `verify_owner`. Recovery revokes all existing tokens and issues new credentials. Without a verified owner email, there is no way to recover a locked-out account.
+
+### What is owner verification?
+
+Owner verification links your personal email address to your agent's InboxAPI account. Your agent calls `verify_owner` with your email, you receive a 6-digit code, and your agent submits it to complete verification. Once verified, you can recover the account if credentials are ever lost, and trial restrictions are removed from the account.
+
 ### What domains are blocked from sending?
 
 InboxAPI maintains a denylist that blocks sending to government (.gov), military (.mil), intelligence, law enforcement, nuclear/critical infrastructure, and disposable email domains.
@@ -344,7 +429,7 @@ Every inbound email is classified into one of four trust levels:
 
 ### What AI model should I use with InboxAPI?
 
-Your model must support **tool/function calling** — MCP requires this. We recommend a minimum **32K token context window** to comfortably fit InboxAPI's 19 tool definitions alongside conversation history and email content.
+Your model must support **tool/function calling** — MCP requires this. We recommend a minimum **32K token context window** to comfortably fit InboxAPI's 21 tool definitions alongside conversation history and email content.
 
 **Model recommendations by tier:**
 
@@ -356,7 +441,7 @@ Your model must support **tool/function calling** — MCP requires this. We reco
 
 **Datamarking overhead:** InboxAPI applies datamarking (spotlighting) to untrusted email content, replacing whitespace with Unicode marker characters. This can slightly increase token consumption when processing emails from external senders. Models with larger context windows handle this more comfortably.
 
-**What won't work:** Models without tool/function calling support, models with context windows under 16K tokens, and very small local models (under ~7B parameters) that lack reliable tool calling. These will struggle to fit InboxAPI's 19 tool definitions and maintain useful conversation history.
+**What won't work:** Models without tool/function calling support, models with context windows under 16K tokens, and very small local models (under ~7B parameters) that lack reliable tool calling. These will struggle to fit InboxAPI's 21 tool definitions and maintain useful conversation history.
 
 ### What stops an agent from buying things or authorizing transactions via email?
 

package/claude/hooks/credential-check.js

@@ -50,8 +50,11 @@ function main() {
   try {
     const creds = JSON.parse(fs.readFileSync(credPath, "utf8"));
     const email = creds.email || creds.account_name || "(unknown)";
+    const encryptionStatus = creds.encryption_secret
+      ? "enabled (secret present in credentials)"
+      : "not configured";
     process.stderr.write(
-      `\n[InboxAPI] Authenticated as: ${email}\n\n`,
+      `\n[InboxAPI] Authenticated as: ${email}\n[InboxAPI] Encryption: ${encryptionStatus}\n\n`,
     );
   } catch {
     process.stderr.write(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inboxapi/cli",
-  "version": "0.2.24",
+  "version": "0.2.25",
   "description": "📧 Email for your AI 🤖",
   "main": "index.js",
   "bin": {
@@ -28,13 +28,13 @@
     "test": "cargo test"
   },
   "optionalDependencies": {
-    "@inboxapi/cli-darwin-arm64": "0.2.24",
-    "@inboxapi/cli-darwin-x64": "0.2.24",
-    "@inboxapi/cli-linux-arm64": "0.2.24",
-    "@inboxapi/cli-linux-x64": "0.2.24",
-    "@inboxapi/cli-win32-x64": "0.2.24"
+    "@inboxapi/cli-darwin-arm64": "0.2.25",
+    "@inboxapi/cli-darwin-x64": "0.2.25",
+    "@inboxapi/cli-linux-arm64": "0.2.25",
+    "@inboxapi/cli-linux-x64": "0.2.25",
+    "@inboxapi/cli-win32-x64": "0.2.25"
   },
   "dependencies": {
-    "@inboxapi/cli": "^0.2.24"
+    "@inboxapi/cli": "^0.2.25"
   }
 }