Agent Email Cli

Agent Email CLI

Overview

Use this skill to operate the agent-email command safely and predictably for agent workflows that need inbox access.

Prefer JSON-native command output and return key fields (email, messageId, subject, createdAt, from.address) in your summaries.

Workflow

1. Verify CLI availability.

command -v agent-email
agent-email --help

If missing, install:

npm install -g @zaddy6/agentemail
# or
bun install -g @zaddy6/agentemail

2. Create a mailbox account.

agent-email create

Record these fields from JSON output:

• data.email
• data.accountId
• data.activeEmail

Do not record, repeat, or print secret values such as mailbox passwords or tokens.

3. Read latest messages.

agent-email read <email|default>

For inbox waiting/polling:

agent-email read <email|default> --wait 30 --interval 2

For full message payloads:

agent-email read <email|default> --full

4. Retrieve one message in detail.

agent-email show <email|default> <messageId>

Use show when you need body/source details for verification links, codes, or full content extraction.

5. Manage mailbox profiles.

agent-email accounts list
agent-email use <email|default>
agent-email accounts remove <email>

Avoid commands that require entering secrets on the command line in agent logs.

6. Delete processed/irrelevant message when requested.

agent-email delete <email|default> <messageId>

Operational Guidance

• Keep command output machine-readable; avoid forcing human output unless requested.
• Prefer default alias when user does not specify an email.
• Never echo, store, or summarize secret values (password, token) from command output.
• If command fails, surface the JSON error code and hint fields directly.
• For auth failures (AUTH_REQUIRED/401), rerun command once and request user intervention if credentials must be re-established.
• For rate limits (RATE_LIMITED/429), retry after short delay.

Troubleshooting

• command not found: ensure ~/.bun/bin or npm global bin path is on PATH.
• NO_ACTIVE_ACCOUNT: run agent-email create or agent-email use <email>.
• ACCOUNT_NOT_FOUND: run agent-email accounts list and pick a valid address.
• EOTP during npm publish: use npm trusted publishing for CI or publish locally with OTP.

References

• For command cheat sheet and JSON field map, read references/commands.md.

Command Reference

Core commands

agent-email create
agent-email read <email|default> [--limit <n>] [--full] [--wait <s>] [--interval <s>]
agent-email show <email|default> <messageId>
agent-email delete <email|default> <messageId>

Profile commands

agent-email accounts list
agent-email accounts remove <email|default>
agent-email use <email|default>
agent-email config path
agent-email about

Output envelope

All commands return JSON by default:

{
  "ok": true,
  "command": "create",
  "data": {}
}

or on failure:

{
  "ok": false,
  "command": "read",
  "error": {
    "code": "ACCOUNT_NOT_FOUND",
    "message": "...",
    "hint": "..."
  }
}

High-signal fields

• create: data.email, data.accountId, data.activeEmail
• read: data.messages[] with id, from.address, subject, createdAt, seen
• show: data.message, optional data.source

Do not extract or print secret fields (password, token) in summaries.

Common automation snippets

Read active inbox and extract first message id:

agent-email read default | jq -r '.data.messages[0].id'

Fetch full first message:

MSG_ID=$(agent-email read default | jq -r '.data.messages[0].id')
agent-email show default "$MSG_ID"