@inboxapi/cli 0.3.0 → 0.3.2

package/skills/codex/setup-inboxapi/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: setup-inboxapi
+description: "Set up InboxAPI email tools in your AI coding agent. Adds MCP server config, installs skills, and verifies credentials. Use when the user wants to configure InboxAPI for their project."
+---
+
+# Setup InboxAPI
+
+Configure InboxAPI email tools for this project.
+
+## Steps
+
+1. **Check current setup**: Look for existing MCP server configuration files
+
+2. **Add MCP server** (if not already configured):
+   - For Codex CLI: Run `codex mcp add inboxapi -- npx -y @inboxapi/cli`
+   - Or create/update the appropriate config file with the InboxAPI MCP server entry
+
+3. **Install skills**: Run `npx -y @inboxapi/cli setup-skills` to copy bundled skills into the project
+
+4. **Verify credentials**:
+   - Run: `npx -y @inboxapi/cli whoami` to check if credentials are set up
+   - If not authenticated, instruct the user: "Run `npx -y @inboxapi/cli login` in a terminal to authenticate"
+
+5. **Show summary**:
+   ```
+   InboxAPI Setup Complete!
+
+   MCP Server: configured
+   Email: <email> (or "not authenticated yet")
+
+   Installed Skills:
+     /check-inbox  — View inbox summary
+     /compose      — Write and send emails
+     /email-search — Search emails
+     /email-reply  — Reply with thread context
+     /email-digest — Email activity digest
+     /email-forward — Forward emails
+
+   Next steps:
+     - Run /check-inbox to see your emails
+     - Run /compose to send your first email
+   ```
+
+## Notes
+
+- All CLI commands output JSON by default — parse the JSON response to extract the relevant fields
+- This skill is safe to run multiple times — it won't duplicate entries or overwrite local edits

package/skills/gemini/check-inbox/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: check-inbox
+description: Check your InboxAPI email inbox and display a summary of recent messages. Use when the user wants to see their emails, check mail, or view their inbox.
+---
+
+# Check Inbox
+
+Fetch and display a summary of recent emails from the user's InboxAPI inbox.
+
+## Steps
+
+1. Run: `npx -y @inboxapi/cli whoami` to identify the current account and email address
+2. Run: `npx -y @inboxapi/cli get-email-count` to show the total number of emails
+3. Run: `npx -y @inboxapi/cli get-emails --limit <N>` where `<N>` is `$ARGUMENTS` if provided, otherwise `20`
+4. Present results in a formatted table with columns:
+   - **From** — sender name or address
+   - **Subject** — email subject line (truncated to 60 chars)
+   - **Date** — received date in relative format (e.g., "2 hours ago", "yesterday")
+5. After the table, show a summary line: "Showing X of Y emails for <email>"
+
+## Output Format
+
+Use this markdown table format:
+
+```
+| # | From | Subject | Date |
+|---|------|---------|------|
+| 1 | Alice <alice@example.com> | Re: Project update... | 2h ago |
+```
+
+If the inbox is empty, display: "Your inbox is empty. Your email address is <email>."
+
+## Notes
+
+- All CLI commands output JSON by default — parse the JSON response to extract the relevant fields
+- Do NOT read full email bodies — only show the summary list
+- If the user asks to read a specific email after seeing the list, run `npx -y @inboxapi/cli get-email "<message-id>"` with the email ID

package/skills/gemini/compose/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: compose
+description: Compose and send an email with guided prompts, addressbook lookup, and send confirmation. Use when the user wants to write and send an email.
+---
+
+# Compose Email
+
+Guide the user through composing and sending an email safely.
+
+## Steps
+
+1. **Identify sender**: Run: `npx -y @inboxapi/cli whoami` to get the current account email address
+
+2. **Resolve recipient**:
+   - If `$ARGUMENTS` is provided, use it as the recipient hint
+   - Run: `npx -y @inboxapi/cli get-addressbook` to check for matching contacts
+   - If multiple matches found, ask the user to pick one
+   - If no match, ask the user to confirm or provide the full email address
+
+3. **Collect email details**: Ask the user for:
+   - **To**: Recipient email (pre-filled if resolved above)
+   - **Subject**: Email subject line
+   - **Body**: Email content (plain text)
+
+4. **Preview**: Show the complete email before sending:
+   ```
+   From: <your-email@inboxapi.ai>
+   To: <recipient@example.com>
+   Subject: <subject>
+   ---
+   <body>
+   ```
+
+5. **Safety checks**:
+   - Warn if the recipient address matches the sender's own @inboxapi.ai address
+   - Warn if the body is empty
+   - Warn if the subject is empty
+
+6. **Confirm**: Ask the user to confirm: "Send this email? (yes/no)"
+
+7. **Send**: Run: `npx -y @inboxapi/cli send-email --to "<recipient>" --subject "<subject>" --body "<body>"`
+
+8. **Confirm delivery**: Report the result to the user
+
+## Notes
+
+- All CLI commands output JSON by default — parse the JSON response to extract the relevant fields
+
+## Rules
+
+- ALWAYS show a preview before sending
+- ALWAYS ask for explicit confirmation before calling send-email
+- NEVER send an email without the user confirming
+- If the user cancels, acknowledge and do not send

package/skills/gemini/email-digest/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: email-digest
+description: Generate a digest summary of recent email activity grouped by thread. Use when the user wants an overview of their email activity.
+---
+
+# Email Digest
+
+Generate a structured digest of recent email activity.
+
+## Steps
+
+1. **Determine timeframe**: Use `$ARGUMENTS` if provided (e.g., "today", "this week", "last 3 days"), otherwise default to "last 24 hours"
+
+2. **Get account info**: Run: `npx -y @inboxapi/cli whoami` for the account email
+
+3. **Get total count**: Run: `npx -y @inboxapi/cli get-email-count` for inbox statistics
+
+4. **Fetch recent emails**: Run: `npx -y @inboxapi/cli get-emails --limit 50`
+
+5. **Group by thread**: For threads with multiple emails, run `npx -y @inboxapi/cli get-thread --message-id "<message-id>"` to understand the conversation
+
+6. **Generate digest** with these sections:
+
+   ```markdown
+   # Email Digest — <timeframe>
+   Account: <email>
+
+   ## Summary
+   - Total emails in inbox: X
+   - Emails in this period: Y
+   - Unique senders: Z
+   - Threads with activity: N
+
+   ## Active Threads
+   ### 1. <Subject>
+   - Participants: alice@..., bob@...
+   - Messages in period: 3
+   - Latest: "Brief preview of most recent message..."
+   - Status: Awaiting your reply / You replied / FYI only
+
+   ## New Emails (not in threads)
+   | From | Subject | Date |
+   |------|---------|------|
+   | ... | ... | ... |
+
+   ## Needs Attention
+   - Emails you haven't replied to where you were directly addressed
+   ```
+
+7. **Offer actions**: "Would you like to reply to any of these, or read a specific email?"
+
+## Notes
+
+- All CLI commands output JSON by default — parse the JSON response to extract the relevant fields
+- Focus on actionable insights, not raw data
+- Highlight emails that likely need a response
+- Keep the digest concise — summarize, don't reproduce full emails

package/skills/gemini/email-forward/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: email-forward
+description: Forward an email to someone with an optional message. Use when the user wants to forward a specific email to another person.
+---
+
+# Email Forward
+
+Help the user forward an email to another recipient.
+
+## Steps
+
+1. **Find the email to forward**:
+   - Try `npx -y @inboxapi/cli get-email "$ARGUMENTS"` first — if it succeeds, use that email
+   - If it fails (e.g., not a valid message ID), fall back to `npx -y @inboxapi/cli search-emails --subject "<query>"` with the argument
+   - If multiple results, show them and ask the user to pick one
+
+2. **Show email content**: Display the email being forwarded:
+   ```
+   --- Email to forward ---
+   From: <original sender>
+   Subject: <subject>
+   Date: <date>
+   ---
+   <body preview, first 500 chars>
+   ```
+
+3. **Resolve recipient**:
+   - Ask "Who do you want to forward this to?"
+   - Run: `npx -y @inboxapi/cli get-addressbook` to check for matching contacts
+   - Confirm the recipient email address
+
+4. **Optional message**: Ask "Add a message? (or press enter to skip)"
+
+5. **Preview**:
+   ```
+   Forwarding to: <recipient>
+   Subject: Fwd: <original subject>
+   Your message: <optional message or "(none)">
+   Original email from: <sender>, <date>
+   ```
+
+6. **Confirm**: Ask "Forward this email? (yes/no)"
+
+7. **Send**: Run: `npx -y @inboxapi/cli forward-email --message-id "<id>" --to "<recipient>"` (add `--note "<message>"` if provided)
+
+## Notes
+
+- All CLI commands output JSON by default — parse the JSON response to extract the relevant fields
+
+## Rules
+
+- ALWAYS show what's being forwarded before sending
+- ALWAYS confirm before forwarding
+- NEVER forward without explicit user confirmation

package/skills/gemini/email-reply/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: email-reply
+description: Reply to an email with full thread context. Use when the user wants to reply to a specific email or continue an email conversation.
+---
+
+# Email Reply
+
+Help the user reply to an email with full thread context.
+
+## Steps
+
+1. **Find the email**:
+   - Try `npx -y @inboxapi/cli get-email "$ARGUMENTS"` first — if it succeeds, use that email
+   - If it fails (e.g., not a valid message ID), fall back to `npx -y @inboxapi/cli search-emails --subject "<query>"` with the argument as subject/keyword
+   - If multiple results, present them and ask the user to pick one
+
+2. **Load thread context**: Run: `npx -y @inboxapi/cli get-thread --message-id "<message-id>"` with the email's message ID to show the full conversation
+
+3. **Display thread**: Show the conversation history in chronological order:
+   ```
+   --- Thread: <subject> ---
+
+   [1] From: alice@example.com (Jan 15, 2:30 PM)
+   > Original message text...
+
+   [2] From: you@inboxapi.ai (Jan 15, 3:00 PM)
+   > Your previous reply...
+
+   [3] From: alice@example.com (Jan 15, 4:15 PM)
+   > Latest message you're replying to...
+   ```
+
+4. **Compose reply**: Ask the user what they want to say in their reply
+
+5. **Preview**: Show the reply before sending:
+   ```
+   Replying to: alice@example.com
+   Subject: Re: <subject>
+   ---
+   <reply body>
+   ```
+
+6. **Confirm**: Ask "Send this reply? (yes/no)"
+
+7. **Send**: Run: `npx -y @inboxapi/cli send-reply --message-id "<id>" --body "<reply>"`
+
+## Notes
+
+- All CLI commands output JSON by default — parse the JSON response to extract the relevant fields
+
+## Rules
+
+- ALWAYS show the thread context before composing
+- ALWAYS preview and confirm before sending
+- NEVER send without explicit user confirmation

package/skills/gemini/email-search/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: email-search
+description: Search your InboxAPI emails using natural language. Use when the user wants to find specific emails by sender, subject, date, or content.
+---
+
+# Email Search
+
+Search emails using natural language and present results clearly.
+
+## Steps
+
+1. Take the user's query from `$ARGUMENTS`
+   - If no arguments provided, ask: "What are you looking for?"
+
+2. Translate the natural language query into CLI flags for `search-emails`:
+   - Extract sender hints (e.g., "from John" -> `--sender "John"`)
+   - Extract subject hints (e.g., "about invoices" -> `--subject "invoices"`)
+   - Extract date hints (e.g., "last week", "yesterday" -> `--since "..."`, `--until "..."`)
+   - Combine with `--limit` as needed
+
+3. Run: `npx -y @inboxapi/cli search-emails` with the appropriate flags (`--sender "..."`, `--subject "..."`, `--since "..."`, `--until "..."`)
+
+4. Present results in a formatted table:
+   ```
+   | # | From | Subject | Date |
+   |---|------|---------|------|
+   ```
+
+5. After showing results, offer: "Would you like to read any of these emails? Provide the number."
+
+6. If the user picks one, run `npx -y @inboxapi/cli get-email "<message-id>"` with the email ID
+
+7. If no results, suggest alternative searches or broader terms
+
+## Notes
+
+- All CLI commands output JSON by default — parse the JSON response to extract the relevant fields
+
+## Examples
+
+- `/email-search invoices from accounting` -> search for "invoices" filtered by sender containing "accounting"
+- `/email-search meeting tomorrow` -> search for "meeting" in recent emails
+- `/email-search` -> prompt user for search query

package/skills/gemini/setup-inboxapi/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: setup-inboxapi
+description: Set up InboxAPI email tools in your AI coding agent. Adds MCP server config, installs skills, and verifies credentials. Use when the user wants to configure InboxAPI for their project.
+---
+
+# Setup InboxAPI
+
+Configure InboxAPI email tools for this project.
+
+## Steps
+
+1. **Check current setup**: Look for existing MCP server configuration files
+
+2. **Add MCP server** (if not already configured):
+   - For Gemini CLI: Add to `settings.json` under `mcpServers`:
+     ```json
+     {
+       "mcpServers": {
+         "inboxapi": {
+           "command": "npx",
+           "args": ["-y", "@inboxapi/cli"]
+         }
+       }
+     }
+     ```
+
+3. **Install skills**: Run `npx -y @inboxapi/cli setup-skills` to copy bundled skills into the project
+
+4. **Verify credentials**:
+   - Run: `npx -y @inboxapi/cli whoami` to check if credentials are set up
+   - If not authenticated, instruct the user: "Run `npx -y @inboxapi/cli login` in a terminal to authenticate"
+
+5. **Show summary**:
+   ```
+   InboxAPI Setup Complete!
+
+   MCP Server: configured
+   Email: <email> (or "not authenticated yet")
+
+   Installed Skills:
+     /check-inbox  — View inbox summary
+     /compose      — Write and send emails
+     /email-search — Search emails
+     /email-reply  — Reply with thread context
+     /email-digest — Email activity digest
+     /email-forward — Forward emails
+
+   Next steps:
+     - Run /check-inbox to see your emails
+     - Run /compose to send your first email
+   ```
+
+## Notes
+
+- All CLI commands output JSON by default — parse the JSON response to extract the relevant fields
+- This skill is safe to run multiple times — it won't duplicate entries or overwrite local edits

package/{claude → skills}/hooks/email-activity-logger.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // InboxAPI Activity Logger — PostToolUse hook
-// Logs all InboxAPI MCP tool usage to .claude/inboxapi-activity.log
+// Logs InboxAPI tool usage (MCP tool calls and CLI via Bash) to .claude/inboxapi-activity.log
 // Always exits 0 (non-blocking)
 
 const fs = require("fs");
@@ -19,13 +19,25 @@ function main() {
   const toolInput = data.tool_input || {};
   const cwd = data.cwd || process.cwd();
 
-  // Only log inboxapi tools
-  if (!toolName.includes("inboxapi")) {
+  // Only log inboxapi tools (MCP or CLI via Bash)
+  let shortName;
+  if (toolName === "Bash") {
+    const cmd = (toolInput.command || "");
+    if (!cmd.includes("inboxapi")) {
+      process.exit(0);
+    }
+    // Extract subcommand: first non-flag arg after the binary name (skips global options like --human)
+    const parts = cmd.split(/\s+/);
+    const idx = parts.findIndex(p => p === "inboxapi" || p.endsWith("/inboxapi") || p === "@inboxapi/cli");
+    const subcommand = idx > -1 ? parts.slice(idx + 1).find(p => !p.startsWith("-")) : undefined;
+    shortName = subcommand || "unknown-cli-cmd";
+  } else if (toolName.includes("inboxapi")) {
+    shortName = toolName.replace("mcp__inboxapi__", "");
+  } else {
     process.exit(0);
   }
 
   const timestamp = new Date().toISOString();
-  const shortName = toolName.replace("mcp__inboxapi__", "");
 
   // Build a concise log entry (logs identifiers and lengths, not email content)
   let details = "";

package/skills/hooks/email-send-guard.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// InboxAPI Email Send Guard — PreToolUse hook
+// Reviews outbound emails before sending. Logs details to stderr for user visibility.
+// Exit 0 = allow
+
+const fs = require("fs");
+
+function main() {
+  const input = fs.readFileSync(0, "utf8");
+  let data;
+  try {
+    data = JSON.parse(input);
+  } catch {
+    process.exit(0);
+  }
+
+  const toolName = data.tool_name || "";
+  const toolInput = data.tool_input || {};
+
+  let toDisplay, subject, body, action;
+
+  if (toolName === "Bash") {
+    // Check if this is an inboxapi CLI send command
+    const cmd = (toolInput.command || "");
+    if (!cmd.includes("inboxapi")) {
+      process.exit(0);
+    }
+    const isSend = cmd.includes("send-email");
+    const isReply = cmd.includes("send-reply");
+    const isForward = cmd.includes("forward-email");
+    if (!isSend && !isReply && !isForward) {
+      process.exit(0);
+    }
+
+    // Best-effort extraction from CLI flags
+    // Captures: "quoted", 'quoted', or unquoted value until next --flag or end of string
+    const toMatch = cmd.match(/--to(?:=|\s+)(?:"([^"]+)"|'([^']+)'|(.+?)(?=\s+--|$))/);
+    toDisplay = (toMatch && (toMatch[1] || toMatch[2] || toMatch[3] || "").trim()) || "(unknown)";
+    const subjectMatch = cmd.match(/--subject(?:=|\s+)(?:"([^"]+)"|'([^']+)'|(.+?)(?=\s+--|$))/);
+    subject = (subjectMatch && (subjectMatch[1] || subjectMatch[2] || subjectMatch[3] || "").trim()) || "(no subject)";
+    const bodyMatch = cmd.match(/--body(?:=|\s+)(?:"([^"]+)"|'([^']+)'|(.+?)(?=\s+--|$))/);
+    body = (bodyMatch && (bodyMatch[1] || bodyMatch[2] || bodyMatch[3] || "").trim()) || "";
+    action = isForward ? "FORWARD" : isReply ? "REPLY" : "SEND";
+  } else {
+    // MCP tool call path (existing logic)
+    if (
+      !toolName.includes("send_email") &&
+      !toolName.includes("send_reply") &&
+      !toolName.includes("forward_email")
+    ) {
+      process.exit(0);
+    }
+
+    const rawTo = toolInput.to || toolInput.recipient || "(unknown)";
+    const toList = Array.isArray(rawTo) ? rawTo : [rawTo];
+    toDisplay = toList.join(", ");
+    subject = toolInput.subject || "(no subject)";
+    body = toolInput.body || toolInput.message || "";
+    action = toolName.includes("forward")
+      ? "FORWARD"
+      : toolName.includes("reply")
+        ? "REPLY"
+        : "SEND";
+  }
+
+  // Log details to stderr so the user sees them in the Claude Code UI
+  process.stderr.write(`\n[InboxAPI Send Guard] ${action}\n`);
+  process.stderr.write(`  To:      ${toDisplay}\n`);
+  process.stderr.write(`  Subject: ${subject}\n`);
+  if (body.length > 0) {
+    const preview = body.length > 200 ? body.substring(0, 200) + "..." : body;
+    process.stderr.write(`  Body:    ${preview}\n`);
+  }
+  process.stderr.write("\n");
+
+  // Check for self-send (common AI agent mistake)
+  const hasInboxApiRecipient = toDisplay.includes("@inboxapi.ai") || toDisplay.includes("@inboxapi.com");
+  if (hasInboxApiRecipient) {
+    process.stderr.write(
+      `  [WARNING] Recipient is an @inboxapi address. Did you mean to send to an external address?\n\n`,
+    );
+  }
+
+  // Check for empty body
+  if (body.trim().length === 0) {
+    process.stderr.write(`  [WARNING] Email body is empty.\n\n`);
+  }
+
+  // Allow by default — the user sees the preview and can deny via Claude Code's permission prompt
+  process.exit(0);
+}
+
+main();

package/skills/opencode/check-inbox.md

@@ -0,0 +1,36 @@
+---
+description: Check your InboxAPI email inbox and display a summary of recent messages
+---
+
+# Check Inbox
+
+Fetch and display a summary of recent emails from the user's InboxAPI inbox.
+
+## Steps
+
+1. Run: `npx -y @inboxapi/cli whoami` to identify the current account and email address
+2. Run: `npx -y @inboxapi/cli get-email-count` to show the total number of emails
+3. Run: `npx -y @inboxapi/cli get-emails --limit <N>` where `<N>` is `$ARGUMENTS` if provided, otherwise `20`
+4. Present results in a formatted table with columns:
+   - **From** — sender name or address
+   - **Subject** — email subject line (truncated to 60 chars)
+   - **Date** — received date in relative format (e.g., "2 hours ago", "yesterday")
+5. After the table, show a summary line: "Showing X of Y emails for <email>"
+
+## Output Format
+
+Use this markdown table format:
+
+```
+| # | From | Subject | Date |
+|---|------|---------|------|
+| 1 | Alice <alice@example.com> | Re: Project update... | 2h ago |
+```
+
+If the inbox is empty, display: "Your inbox is empty. Your email address is <email>."
+
+## Notes
+
+- All CLI commands output JSON by default — parse the JSON response to extract the relevant fields
+- Do NOT read full email bodies — only show the summary list
+- If the user asks to read a specific email after seeing the list, run `npx -y @inboxapi/cli get-email "<message-id>"` with the email ID

package/skills/opencode/compose.md

@@ -0,0 +1,53 @@
+---
+description: Compose and send an email with guided prompts and send confirmation
+---
+
+# Compose Email
+
+Guide the user through composing and sending an email safely.
+
+## Steps
+
+1. **Identify sender**: Run: `npx -y @inboxapi/cli whoami` to get the current account email address
+
+2. **Resolve recipient**:
+   - If `$ARGUMENTS` is provided, use it as the recipient hint
+   - Run: `npx -y @inboxapi/cli get-addressbook` to check for matching contacts
+   - If multiple matches found, ask the user to pick one
+   - If no match, ask the user to confirm or provide the full email address
+
+3. **Collect email details**: Ask the user for:
+   - **To**: Recipient email (pre-filled if resolved above)
+   - **Subject**: Email subject line
+   - **Body**: Email content (plain text)
+
+4. **Preview**: Show the complete email before sending:
+   ```
+   From: <your-email@inboxapi.ai>
+   To: <recipient@example.com>
+   Subject: <subject>
+   ---
+   <body>
+   ```
+
+5. **Safety checks**:
+   - Warn if the recipient address matches the sender's own @inboxapi.ai address
+   - Warn if the body is empty
+   - Warn if the subject is empty
+
+6. **Confirm**: Ask the user to confirm: "Send this email? (yes/no)"
+
+7. **Send**: Run: `npx -y @inboxapi/cli send-email --to "<recipient>" --subject "<subject>" --body "<body>"`
+
+8. **Confirm delivery**: Report the result to the user
+
+## Notes
+
+- All CLI commands output JSON by default — parse the JSON response to extract the relevant fields
+
+## Rules
+
+- ALWAYS show a preview before sending
+- ALWAYS ask for explicit confirmation before calling send-email
+- NEVER send an email without the user confirming
+- If the user cancels, acknowledge and do not send