---

name: inbound-cli description: Use the Inbound CLI to manage mailbox profiles, list and read emails, and keep an agent's default mailbox context between sessions.

inbound-cli

Use this skill to operate email workflows through the inbound CLI with a persistent mailbox profile (inbound.json).

Setup

• Install globally: npm i -g inbound-cli
• Use command name: inbound

When to use

• User asks to check inbox mail, triage unread items, read email threads, or reply using Inbound CLI.
• User asks to set up or switch mailbox defaults for the agent.
• User asks to filter email activity by mailbox address/domain.
• User asks for command-line email operations instead of direct API calls.

Do not use this skill when the task is unrelated to Inbound email workflows.

Instructions

1. Validate CLI availability.

   • Ensure global install exists: npm i -g inbound-cli.
   • Verify command works: inbound help.

2. Validate auth before mailbox work.

   • Check INBOUND_API_KEY exists.
   • If missing, ask the user for the API key or ask them to export it.

3. Ensure mailbox profile exists for the agent.

   • If no config exists, initialize: inbound mailbox init.
   • Add mailbox profile for the agent identity:
     • inbound mailbox add <key> --name "<Agent Name>" --email <agent@email> [--domain <domain>]
   • Set default mailbox:
     • inbound mailbox use <key>

4. Default mailbox-first inbox workflow.

   • List inbox (defaults to received type):
     • inbound emails list --limit 25
   • Read a specific email:
     • inbound emails get <email_id>
   • Mark handled email as read:
     • inbound emails update <email_id> --is_read true

5. Use filters intentionally.

   • Narrow by status/search/time:
     • inbound emails list --status unread --search "invoice" --time-range 7d
   • Override mailbox filters for one run:
     • inbound emails list --address user@example.com
     • inbound emails list --domain example.com
   • Include non-received types when needed:
     • inbound emails list --type sent
     • inbound emails list --type scheduled
     • inbound emails list --type all

6. Find mailbox profiles by identity.

   • inbound mailbox find --address user@example.com
   • inbound mailbox find --domain example.com

7. Use thread view for conversation context.

   • inbound mail threads list --limit 20
   • inbound mail threads get <thread_id>

8. Automation and parsing mode.

   • Use --json when the output needs machine parsing.
   • Use human mode by default for operator readability.

Expected behavior

• Always start from the configured default mailbox unless explicit filter overrides are provided.
• Preserve mailbox context so future runs use the same identity.
• Keep user informed when filters broaden scope (for example --type all).

Quick command cheatsheet

inbound mailbox list
inbound mailbox show
inbound emails list --status unread --limit 25
inbound emails get <email_id>
inbound emails update <email_id> --is_read true
inbound mail threads list --limit 20
inbound mail threads get <thread_id>
inbound emails list --json