AgentMail CLI

Use the agentmail CLI to send and receive emails programmatically. Requires AGENTMAIL_API_KEY environment variable.

Install

npm install -g agentmail-cli

Core Commands

Inboxes

# Create an inbox (defaults to @agentmail.to;
# pass --domain only if you have verified a custom domain)
agentmail inboxes create --display-name "My Agent" --username myagent

# List inboxes
agentmail inboxes list

# Get an inbox
agentmail inboxes retrieve --inbox-id <inbox_id>

# Delete an inbox
agentmail inboxes delete --inbox-id <inbox_id>

Send Email

# Send a message from an inbox
agentmail inboxes:messages send --inbox-id <inbox_id> \
  --to "recipient@example.com" \
  --subject "Hello" \
  --text "Message body"

# Send with HTML
agentmail inboxes:messages send --inbox-id <inbox_id> \
  --to "recipient@example.com" \
  --subject "Hello" \
  --html "<h1>Hello</h1>"

# Reply to a message
agentmail inboxes:messages reply --inbox-id <inbox_id> --message-id <message_id> \
  --text "Reply body"

# Forward a message
agentmail inboxes:messages forward --inbox-id <inbox_id> --message-id <message_id> \
  --to "someone@example.com"

Read Email

# List messages in an inbox
agentmail inboxes:messages list --inbox-id <inbox_id>

# Get a specific message
agentmail inboxes:messages retrieve --inbox-id <inbox_id> --message-id <message_id>

# List threads
agentmail inboxes:threads list --inbox-id <inbox_id>

# Get a thread
agentmail inboxes:threads retrieve --inbox-id <inbox_id> --thread-id <thread_id>

Drafts

# Create a draft
agentmail inboxes:drafts create --inbox-id <inbox_id> \
  --to "recipient@example.com" \
  --subject "Draft" \
  --text "Draft body"

# Send a draft
agentmail inboxes:drafts send --inbox-id <inbox_id> --draft-id <draft_id>

Pods

Pods group inboxes together.

# Create a pod
agentmail pods create --name "My Pod"

# Create an inbox in a pod
agentmail pods:inboxes create --pod-id <pod_id> --display-name "Pod Inbox"

# List threads in a pod
agentmail pods:threads list --pod-id <pod_id>

Webhooks

# Create a webhook for new messages
agentmail webhooks create --url "https://example.com/webhook" --event-type message.received

# List webhooks
agentmail webhooks list

Domains

# Add a custom domain. --feedback-enabled is REQUIRED:
# pass the flag to route bounce/complaint notifications to your inboxes.
# The CLI has no way to create a domain without this flag.
agentmail domains create --domain example.com --feedback-enabled

# Verify domain DNS
agentmail domains verify --domain-id <domain_id>

# Get DNS records to configure
agentmail domains get-zone-file --domain-id <domain_id>

Global Flags

All commands support: --api-key, --base-url, --environment, --format, --format-error, --transform, --transform-error, --debug.

Output Formats

Use --format to control output: auto (default), pretty, json, jsonl, yaml, raw, explore.