AgentMail CLI

A command-line interface for AgentMail - manage email inboxes and messages from your terminal.

Installation

# Install globally
npm install -g @stepandel/agentmail-cli
# Or run directly with npx
npx @stepandel/agentmail-cli

Configuration

API Key

Set your API key using one of these methods:

Option 1: Environment variable (recommended for CI/CD)

export AGENTMAIL_API_KEY=your-api-key

Option 2: Config file

agentmail config set-key your-api-key

The config file is stored at ~/.agentmail/config.json.

View Configuration

agentmail config show

Usage

Inbox Commands

Create an inbox:

# Create with auto-generated email
agentmail inbox create
# Create with custom domain
agentmail inbox create --domain example.com
# Create with specific username
agentmail inbox create --username support --domain example.com
# Create with display name
agentmail inbox create --display-name "Support Team"

List all inboxes:

agentmail inbox list
# Limit results
agentmail inbox list --limit 10

Get inbox details:

agentmail inbox get <inbox-id>

Delete an inbox:

agentmail inbox delete <inbox-id>

Message Commands

Send a message:

# Basic message
agentmail message send \
--from <inbox-id> \
--to recipient@example.com \
--subject "Hello" \
--text "Hello, World!"# With HTML body
agentmail message send \
--from <inbox-id> \
--to recipient@example.com \
--subject "Hello" \
--html "<h1>Hello</h1><p>World!</p>"# Multiple recipients
agentmail message send \
--from <inbox-id> \
--to "one@example.com,two@example.com" \
--subject "Hello" \
--text "Hello everyone!"# With CC and BCC
agentmail message send \
--from <inbox-id> \
--to recipient@example.com \
--cc "cc1@example.com,cc2@example.com" \
--bcc hidden@example.com \
--subject "Hello" \
--text "Hello, World!"

List messages in an inbox:

agentmail message list <inbox-id># Limit results
agentmail message list <inbox-id> --limit 20

Get a specific message:

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

Delete a message:

agentmail message delete <inbox-id><message-id>

Note: Deleting a message deletes the entire thread containing that message.

Output Formats

All commands support a --json flag for machine-readable output:

# Human-readable (default)
agentmail inbox list
# JSON output
agentmail inbox list --json

JSON Output Examples

Inbox list:

{
"count": 2,
"inboxes": [
{
"inboxId": "abc123",
"podId": "pod_xyz",
"displayName": "Support",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}
]
}

Send message response:

{
"messageId": "msg_abc123",
"threadId": "thread_xyz789"
}

Help

# General help
agentmail --help
# Command-specific help
agentmail inbox --help
agentmail message --help
agentmail config --help

Environment Variables

Variable	Description
AGENTMAIL_API_KEY	API key for authentication (takes precedence over config file)

Examples

Workflow: Create inbox and send email

# 1. Configure API keyexport AGENTMAIL_API_KEY=your-api-key
# 2. Create an inbox
agentmail inbox create --json | tee inbox.json
INBOX_ID=$(cat inbox.json | jq -r '.inboxId')# 3. Send an email
agentmail message send \
--from "$INBOX_ID" \
--to customer@example.com \
--subject "Welcome!" \
--text "Thanks for signing up!"# 4. Check for responses
agentmail message list "$INBOX_ID"

Workflow: Process incoming messages

# Get all messages as JSON for processing
agentmail message list "$INBOX_ID" --json | jq '.messages[] | {from, subject}'

License

MIT