agentmail-cli
agentmail-to/agentmail-skills
Official CLI for AgentMail—manage inboxes, messages, drafts, and webhooks from the shell.
What is agentmail-cli?
AgentMail CLI is a command-line tool for operating AgentMail email infrastructure. Use it when you need to list or create inboxes, read or search mail, send or reply to messages, manage drafts, or script operations with JSON/YAML output.
- List, create, and delete inboxes
- Send, reply to, and forward messages with plain text or HTML bodies
- Create, list, and send drafts
- Manage message threads and search mail
- Create and manage pods (inbox groups)
- Set up webhooks for message events and domain bounce/complaint notifications
How to install agentmail-cli
npx skills add https://github.com/agentmail-to/agentmail-skills --skill agentmail-cli- Node.js and npm installed
- AgentMail API key (set as AGENTMAIL_API_KEY environment variable)
How to use agentmail-cli
- 1.Install globally: npm install -g agentmail-cli
- 2.Export your API key: export AGENTMAIL_API_KEY="am_..."
- 3.List inboxes: agentmail inboxes list
- 4.Create an inbox: agentmail inboxes create --display-name "Name" --username username
- 5.Send a message: agentmail inboxes:messages send --inbox-id <id> --to recipient@example.com --subject "Subject" --text "Body"
- 6.Use --format json or --format yaml to script output
- 7.Check agentmail --help for additional commands and flags
Use cases
- Automate email operations in shell scripts or CI/CD pipelines
- Build support agent workflows that read and reply to customer mail
- Create and manage multiple branded inboxes for different purposes
- Set up webhook integrations to trigger actions on incoming messages
- Configure custom domains with bounce/complaint feedback routing
- DevOps engineers automating email workflows
- Backend developers integrating AgentMail into applications
- Support teams scripting bulk email operations
- Anyone building email-driven agents or automation
agentmail-cli FAQ
Use the --html flag instead of --text when calling inboxes:messages send or inboxes:drafts create.
Yes. Create multiple inboxes with agentmail inboxes create, then reference each by --inbox-id in subsequent commands.
Run agentmail webhooks create --url "https://your-endpoint" --event-type message.received to receive notifications when mail arrives.
The --format flag accepts: auto, pretty, json, jsonl, yaml, raw, and explore. Use json or yaml for scripting.
No, it's optional. Use agentmail domains create if you want to send mail from your own domain and route bounce/complaint feedback.
Full instructions (SKILL.md)
Source of truth, from agentmail-to/agentmail-skills.
name: agentmail-cli description: Operate AgentMail from a shell with the official CLI. Use when the user wants commands for listing or creating inboxes, reading or searching mail, sending or replying, managing drafts, or scripting JSON/YAML output; do not use for SDK code, MCP setup, or framework adapters.
AgentMail CLI
Install the CLI and provide the API key through the environment.
npm install -g agentmail-cli
export AGENTMAIL_API_KEY="am_..."
Subcommands for a resource nested under another use a colon, e.g. inboxes:messages, inboxes:threads, pods:inboxes, pods:threads.
Inboxes
agentmail inboxes list
agentmail inboxes get --inbox-id <inbox_id>
agentmail inboxes create --display-name "Support Agent" --username support
agentmail inboxes delete --inbox-id <inbox_id>
Confirm the exact inbox before running the destructive delete command.
Messages and threads
agentmail inboxes:messages list --inbox-id <inbox_id>
agentmail inboxes:messages get --inbox-id <inbox_id> --message-id <message_id>
agentmail inboxes:messages send --inbox-id <inbox_id> \
--to "recipient@example.com" \
--subject "Hello" \
--text "Message body"
# HTML body instead of plain text
agentmail inboxes:messages send --inbox-id <inbox_id> \
--to "recipient@example.com" \
--subject "Hello" \
--html "<h1>Hello</h1>"
agentmail inboxes:messages reply --inbox-id <inbox_id> \
--message-id <message_id> \
--text "Reply body"
agentmail inboxes:messages forward --inbox-id <inbox_id> \
--message-id <message_id> \
--to "someone@example.com"
agentmail inboxes:threads list --inbox-id <inbox_id>
agentmail inboxes:threads get --inbox-id <inbox_id> --thread-id <thread_id>
Use a message ID for replies. Fetch the full message before relying on body content.
Drafts
agentmail inboxes:drafts create --inbox-id <inbox_id> \
--to "recipient@example.com" \
--subject "Pending approval" \
--text "Draft body"
agentmail inboxes:drafts list --inbox-id <inbox_id>
agentmail inboxes:drafts get --inbox-id <inbox_id> --draft-id <draft_id>
agentmail inboxes:drafts send --inbox-id <inbox_id> --draft-id <draft_id>
Pods
Pods group inboxes together.
agentmail pods create --name "My Pod"
agentmail pods list
agentmail pods:inboxes create --pod-id <pod_id> --display-name "Pod Inbox"
agentmail pods:inboxes list --pod-id <pod_id>
agentmail pods:threads list --pod-id <pod_id>
agentmail pods:threads get --pod-id <pod_id> --thread-id <thread_id>
Webhooks
agentmail webhooks create --url "https://example.com/webhook" --event-type message.received
agentmail webhooks list
Domains
agentmail domains create --domain example.com
# Optional: route bounce/complaint notifications to your inboxes.
agentmail domains create --domain example.com --feedback-enabled
agentmail domains verify --domain-id <domain_id>
agentmail domains get-zone-file --domain-id <domain_id>
Global flags
| Flag | Purpose |
|---|---|
--api-key | Override AGENTMAIL_API_KEY for this call |
--base-url | Point at a non-default API host |
--environment | Select a named environment |
--format | Output format (see below) |
--format-error | Control structured error output |
--transform | GJSON projection of a successful response |
--transform-error | GJSON projection of an error response |
--debug | Verbose request/response logging |
Output formats
--format accepts: auto (default), pretty, json, jsonl, yaml, raw, explore.
Run agentmail --help and the relevant resource's --help before using an administrative command not covered here.
Related skills
More from agentmail-to/agentmail-skills and the wider catalog.
agentmail
Build email workflows for AI agents with the AgentMail TypeScript or Python SDK.
polymarket-api
Deep integration guide for Polymarket's CLOB API, Gamma API, and on-chain data. Use when building trading functionality, fetching market data, or implementing order execution.
trading-strategies
Framework for developing, testing, and deploying trading strategies for prediction markets.
authsome
Transparently inject stored credentials into HTTP requests for external APIs and services.
agent-native-design
Design and review CLIs that work reliably for AI agents, humans, and orchestration systems.
asta-skill
Domain expertise for Ai2 Asta MCP tools—academic paper search, citation traversal, and author discovery on Semantic Scholar.