imap-agent-cli 0.1.2

Agent-first IMAP CLI for safe email search, read, attachment download, and draft creation

imap-agent-cli

imap-agent-cli is an agent-first IMAP CLI for safe email search, read, attachment download, and draft creation.

It can inspect mailboxes and append messages to Drafts. It cannot send email, delete messages, move messages, archive messages, change labels, alter flags, or mark messages read/unread.

Status

This repo is under active development. The behavior target is defined in spec.md.

Quick Start

Single-profile env-var setup:

IMAP_AGENT_CLI_HOST=imap.example.com
IMAP_AGENT_CLI_PORT=993
IMAP_AGENT_CLI_USERNAME=[e-mail]
IMAP_AGENT_CLI_PASSWORD=...
IMAP_AGENT_CLI_TLS=true

Local development:

uv run ./imap_agent_cli.py --help
uv run ./imap_agent_cli.py folders
uv run ./imap_agent_cli.py search --subject invoice

Packaged execution:

uvx imap-agent-cli --help

Examples

imap-agent-cli folders
imap-agent-cli search --folder INBOX --subject "invoice" --max-results 10
imap-agent-cli read --folder INBOX --uid 12345 --body-format html
imap-agent-cli attachments --folder INBOX --uid 12345
imap-agent-cli attachments download --folder INBOX --uid 12345 --part-id 2 --output-dir C:\tmp\email-attachments
imap-agent-cli draft create --to [e-mail] --subject "Hello" --body "Draft only."
imap-agent-cli draft reply --folder INBOX --uid 12345 --body "Thanks. I will review this."

All command payloads are JSON on stdout. Diagnostics and errors go to stderr.

Config

Create a starter config:

imap-agent-cli config init

Add a named profile:

imap-agent-cli config add-profile work --host imap.example.com --port 993 --username [e-mail] --password-env IMAP_AGENT_CLI_WORK_PASSWORD
imap-agent-cli config set-default-profile work

Config path:

~/.imap-agent-cli/config.toml

Secrets should stay in environment variables, not the config file.

Codex Skill

Install or update the user-scoped Codex skill:

imap-agent-cli install-skill

This writes:

~/.agents/skills/imap/SKILL.md

Remove the managed skill:

imap-agent-cli remove-skill

Use --skills-dir PATH to install into a nonstandard skills directory, for example:

imap-agent-cli install-skill --skills-dir C:\Users\PaulEllis\.agents\skills

Safety Boundary

Allowed:

• list folders
• search messages
• read messages with no-seen fetch behavior
• list/download attachments only when requested
• append new messages to Drafts

Not allowed:

• send
• delete
• move
• archive
• flag/star
• mark read/unread
• create/delete/rename folders

Testing

No-network unit tests:

python -m unittest discover -v

Package build:

uv build --no-sources

The spec targets pymap for future local IMAP integration tests on Windows without Docker.

Opt-in local IMAP integration test:

$env:IMAP_AGENT_CLI_TEST_PYMAP = "1"
uv run --extra test python -m unittest tests.test_pymap_integration -v

The integration test starts pymap dict --demo-data locally and logs in with demouser / demopass.

Publishing

The GitHub Actions workflow is .github/workflows/publish.yml.

PyPI Trusted Publishing values:

Project: imap-agent-cli
Owner: pseudosavant
Repository: imap-agent-cli
Workflow: publish.yml
Environment: pypi