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 <inbox-id> --json

Delete an inbox:

agentmail inbox delete <inbox-id>

Message Commands

Send a message:

agentmail message send --from <inbox-id> --to recipient@example.com --subject "Subject" --text "Body text" --json

Send with HTML:

agentmail message send --from <inbox-id> --to recipient@example.com --subject "Subject" --html "<h1>Hello</h1>" --json

Multiple recipients, CC, BCC:

agentmail message send --from <inbox-id> --to "a@example.com,b@example.com" --cc "cc@example.com" --bcc "bcc@example.com" --subject "Subject" --text "Body" --json

List messages in an inbox:

agentmail message list <inbox-id> --json
agentmail message list <inbox-id> --limit 20 --json

Get a specific message:

agentmail message get <inbox-id> <message-id> --json

Delete a message (deletes entire thread):

agentmail message delete <inbox-id> <message-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 user@example.com --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