agentmail-cli

CLI for AgentMail — create inboxes, send messages, and read email.

API Key Setup

The API key MUST be configured before any command will work. Two methods:

1. Config file (preferred for persistent agents):

agentmail config set-key YOUR_API_KEY

This stores the key at ~/.agentmail/config.json and persists across sessions.

2. Environment variable:

export AGENTMAIL_API_KEY=YOUR_API_KEY

Verify configuration:

agentmail config show

If commands fail with auth errors, re-run agentmail config set-key — the env var alone may not persist between shell sessions.

Always Use --json

Always pass --json to every command for machine-readable output. Parse with jq when needed.

Inbox Commands

Create an inbox:

agentmail inbox create --json
agentmail inbox create --domain example.com --json
agentmail inbox create --username support --domain example.com --display-name "Support Team" --json

List inboxes:

agentmail inbox list --json
agentmail inbox list --limit 10 --json

Get inbox details:

agentmail inbox get \x3Cinbox-id> --json

Delete an inbox:

agentmail inbox delete \x3Cinbox-id>

Message Commands

Send a message:

agentmail message send --from \x3Cinbox-id> --to [email protected] --subject "Subject" --text "Body text" --json

Send with HTML:

agentmail message send --from \x3Cinbox-id> --to [email protected] --subject "Subject" --html "\x3Ch1>Hello\x3C/h1>" --json

Multiple recipients, CC, BCC:

agentmail message send --from \x3Cinbox-id> --to "[email protected],[email protected]" --cc "[email protected]" --bcc "[email protected]" --subject "Subject" --text "Body" --json

List messages in an inbox:

agentmail message list \x3Cinbox-id> --json
agentmail message list \x3Cinbox-id> --limit 20 --json

Get a specific message:

agentmail message get \x3Cinbox-id> \x3Cmessage-id> --json

Delete a message (deletes entire thread):

agentmail message delete \x3Cinbox-id> \x3Cmessage-id>

Common Workflow

# 1. Create inbox, capture ID
INBOX_ID=$(agentmail inbox create --json | jq -r '.inboxId')

# 2. Send email
agentmail message send --from "$INBOX_ID" --to [email protected] --subject "Hello" --text "Message body" --json

# 3. Check for replies
agentmail message list "$INBOX_ID" --json

Notes

• Get an API key at https://agentmail.to
• Config file location: ~/.agentmail/config.json
• Env var AGENTMAIL_API_KEY takes precedence over config file
• Deleting a message deletes the entire thread containing it