agentmail-cli

Manage email inboxes and messages via AgentMail API. Create disposable inboxes, send/receive emails, and list messages. Use when the agent needs to send or receive email, create temporary inboxes, or check for incoming messages.

Security Scan

The skill's requirements and runtime instructions align with its stated purpose (a CLI wrapper for AgentMail); nothing requested appears unrelated or excessive, though installing an npm package and storing an API key on disk have the usual operational risks to consider.

Purpose & Capability

Name/description, required binary (agentmail), primary env var (AGENTMAIL_API_KEY), and the declared npm install (@stepandel/agentmail-cli) are all consistent: the skill is a CLI client for AgentMail and requests exactly the API key and binary needed to operate.

Instruction Scope

SKILL.md only instructs use of the agentmail CLI (create/list/delete inboxes, send/list/get/delete messages) and how to configure the API key via env var or ~/.agentmail/config.json. It does not ask the agent to read unrelated files, query other credentials, or post data to unexpected endpoints.

Install Mechanism

Install is via an npm package (@stepandel/agentmail-cli) which will place an 'agentmail' binary on PATH. This is a standard approach but carries the usual npm-origin risks (supply-chain/malicious package); verify the package/author and review code before installing in sensitive environments.

Credentials

Only AGENTMAIL_API_KEY is required and it is the natural credential for an email-sending/receiving service. The SKILL.md documents config file location (~/.agentmail/config.json) and that the env var takes precedence — storing the key unencrypted on disk is expected behavior but worth noting.

Persistence & Privilege

always:false (no forced persistence). The skill instructs the CLI to persist the API key to ~/.agentmail/config.json if the user runs 'agentmail config set-key' — this is appropriate for a CLI but means persistent plaintext storage of credentials unless the user avoids that step.

Assessment

This skill appears to be what it says: a CLI wrapper for AgentMail that needs an API key. Before installing, verify the npm package and GitHub repo (author, recent commits, downloads) and inspect the package contents if you can. Be aware that the CLI can persist your AGENTMAIL_API_KEY to ~/.agentmail/config.json in plaintext if you use 'agentmail config set-key' — if you prefer not to leave credentials on disk, use an environment variable for ephemeral sessions and revoke the key afterward. Limit the API key's permissions (if the service supports it), and avoid installing the package on high-value hosts until you inspect the code or run it in a sandbox.

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 [e-mail] --subject "Subject" --text "Body text" --json

Send with HTML:

agentmail message send --from <inbox-id> --to [e-mail] --subject "Subject" --html "<h1>Hello</h1>" --json

Multiple recipients, CC, BCC:

agentmail message send --from <inbox-id> --to "[e-mail],[e-mail]" --cc "[e-mail]" --bcc "[e-mail]" --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 [e-mail] --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