agent-email

agent-email is a Bun CLI for AI agents that need access to a disposable email inbox powered by Mail.tm.

Open Source

This project is open source under the MIT License.

Community docs:

• Contributing
• Releasing
• Code of Conduct
• Security Policy

Install

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

Install the Codex skill:

npx skills add https://github.com/zaddy6/agent-email-skill --skill agent-email-cli

Quick Start

Create an inbox with one command (no flags):

agent-email create

Read latest emails:

agent-email read <email>

All commands return JSON by default.

Commands

• agent-email create
• agent-email read <email|alias> [--limit <n>] [--full] [--wait <seconds>] [--interval <seconds>]
• agent-email show <email|alias> <messageId>
• agent-email delete <email|alias> <messageId>
• agent-email accounts list
• agent-email accounts add <email> --password <pwd> [--set-default]
• agent-email accounts remove <email|alias>
• agent-email use <email|alias>
• agent-email config path
• agent-email about

Aliases for account selection:

• default
• active
• me

Use human-readable output if needed:

agent-email --human accounts list

Config

Credentials are stored in:

• ~/.config/agent-email/config.json

Override path with:

• AGENT_EMAIL_CONFIG=/custom/path/config.json

The tool enforces 0600 permissions for the config file on Unix.

Development

bun install
bun run check

Run live Mail.tm smoke test (opt-in):

AGENT_EMAIL_LIVE_TESTS=1 bun run test:live

API and Attribution

This project uses Mail.tm API. If you use the API, follow Mail.tm terms and attribution requirements.