jmax 0.1.0

Agent-friendly JMAP email CLI. Flat verbs, JSON by default, exit codes that mean something.

jmax

Agent-friendly JMAP email CLI. Flat verbs, JSON-by-default, exit codes that mean something.

It exists because every other "mail CLI" is either Fastmail-only, written for humans with a pager and a color scheme, or shipped as part of a mail client. None of them are good for scripting or for AI agents. jmax is.

Install

uv tool install jmax
# or
uvx jmax inbox

Python 3.10+. Only runtime dependency is httpx.

Configure

Env vars only — no dotfiles.

export JMAP_URL=https://mail.example.com/jmap      # or https://api.fastmail.com/jmap
export JMAP_USER=[e-mail]
export JMAP_PASSWORD=...                           # or JMAP_TOKEN for bearer auth
# optional:
export JMAP_ACCOUNT_ID=...                         # auto-discovered if omitted

Any of those can be overridden per-call with --url, --user, --password, --token, --account-id.

Commands

jmax inbox [--unread] [--limit N] [--since 7d|24h|ISO] [--count]
jmax mailboxes
jmax search <query> [--from X] [--in MAILBOX] [--unread] [--since ...]
jmax get <id> [--headers | --body | --attachments | --subject]
jmax read <id>...
jmax unread <id>...
jmax flag <id>...
jmax unflag <id>...
jmax move <id>... --to <mailbox>
jmax trash <id>...
jmax delete <id>... [--permanent] [--yes]
jmax send --to X --subject Y [--body-file F | stdin]
jmax reply <id> [--body-file F | stdin]
jmax attachment <email-id> <filename> [-o FILE]

All commands accept --table (where applicable), --dry-run (where mutating), and --yes (where destructive).

Output contract

• Scalars → plain stdout. jmax inbox --count prints 42. jmax get e1 --subject prints Hello.
• Lists/objects → JSON by default. Pipe into jq, loop over it, assert on it.
• Mutations → silent on success. Noise is a bug.
• --table → human-readable table for lists. Opt-in, never the default.

Exit codes

Code	Meaning
0	Success
1	Ran fine, returned no results or the ID wasn't there
2	Something broke — auth, network, bad args, server error

So jmax search urgent && echo 'got some' works the way you'd hope.

Safety

Destructive operations refuse to run without --yes:

• jmax delete --permanent
• jmax delete / jmax trash on more than 10 IDs at once

Every mutating command supports --dry-run, which prints the raw JMAP methodCall instead of executing. Hand that to an agent when you want it to "show its work" before the real run.

Recipes for agents

# How many unread emails in the last day?
jmax inbox --unread --since 24h --count

# Dump every sender from this month into a CSV:
jmax search "" --since 30d --limit 1000 | jq -r '.[] | .from' | sort -u

# Archive every newsletter:
jmax search "" --from "newsletter@" --limit 500 \
  | jq -r '.[].id' \
  | xargs -n50 jmax move --to Archive

# Show subject, then reply:
jmax get $ID --subject
echo "Thanks!" | jmax reply $ID

Design principles

• Do one thing per command. No multiplexed "smart" verbs.
• Trust the server. JMAP queries are cheap; there's no local cache, no sync, no database. Every invocation re-queries. The agent's memory is the agent's problem.
• Don't pretty-print by default. The default consumer is a pipe.
• Env-var config, no files. Like gh, like aws. Simpler to reason about.
• Fail loud. No silent retries on auth failure. Fix the env var.

Supported servers

Built against Stalwart and Fastmail. Any RFC 8620 / RFC 8621 server should work — file an issue if yours doesn't.

License

MIT.