Inbound CLI
Apps & Automationinbound-cliInbound CLI is an Agent Skill for apps & automation published in the inboundemail/inbound repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use the Inbound CLI to manage mailbox profiles, list and read emails, and keep an agent's default mailbox context between sessions.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/inboundemail/inbound/blob/HEAD/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/inbound-cli, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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
-
Validate CLI availability.
- Ensure global install exists:
npm i -g inbound-cli. - Verify command works:
inbound help.
- Ensure global install exists:
-
Validate auth before mailbox work.
- Check
INBOUND_API_KEYexists. - If missing, ask the user for the API key or ask them to export it.
- Check
-
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>
- If no config exists, initialize:
-
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
- List inbox (defaults to received type):
-
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 [email protected]inbound emails list --domain example.com
- Include non-received types when needed:
inbound emails list --type sentinbound emails list --type scheduledinbound emails list --type all
- Narrow by status/search/time:
-
Find mailbox profiles by identity.
inbound mailbox find --address [email protected]inbound mailbox find --domain example.com
-
Use thread view for conversation context.
inbound mail threads list --limit 20inbound mail threads get <thread_id>
-
Automation and parsing mode.
- Use
--jsonwhen the output needs machine parsing. - Use human mode by default for operator readability.
- Use
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