AgentMail Core

Common CLI path: create inboxes, send mail, read incoming mail, reply in threads, label work, and fetch attachments. Need a key first? Use signup.md. Need realtime delivery? Use webhooks.md or websockets.md.

Setup

bash

npm install -g agentmail-cli@latest
export AGENTMAIL_API_KEY="am_..."
agentmail inboxes list --format json

Inboxes

bash

agentmail inboxes create \
  --username support \
  --display-name "Support Agent" \
  --client-id support-agent-primary \
  --format json

agentmail inboxes get --inbox-id [email protected] --format json

Omit domain to use @agentmail.to. Use stable client_id values for retried create commands.

Send

bash

agentmail inboxes:messages send \
  --inbox-id [email protected] \
  --to [email protected] \
  --subject "Hello" \
  --text "Plain-text body." \
  --html "<p>Plain-text body.</p>" \
  --label outreach \
  --format json

Send both text and html when possible. Recipient limit is 50 total across to, cc, and bcc.

Read and Reply

bash

agentmail inboxes:messages list --inbox-id [email protected] --label unread --format json
agentmail inboxes:messages get --inbox-id [email protected] --message-id <message_id> --format json
agentmail inboxes:threads get --inbox-id [email protected] --thread-id <thread_id> --format json

For LLM input, prefer extracted_text or extracted_html. Some email has html but no text.

bash

agentmail inboxes:messages reply \
  --inbox-id [email protected] \
  --message-id <message_id> \
  --text "Thanks, I will take a look." \
  --format json

agentmail inboxes:messages reply-all \
  --inbox-id [email protected] \
  --message-id <message_id> \
  --text "Thanks, everyone." \
  --format json

agentmail inboxes:messages forward \
  --inbox-id [email protected] \
  --message-id <message_id> \
  --to [email protected] \
  --format json

Labels

Use labels as lightweight state: unread, handled, needs-review.

bash

agentmail inboxes:messages update \
  --inbox-id [email protected] \
  --message-id <message_id> \
  --add-labels handled \
  --remove-labels unread \
  --format json

Attachments

bash

agentmail inboxes:messages get-attachment \
  --inbox-id [email protected] \
  --message-id <message_id> \
  --attachment-id <attachment_id> \
  --format json

Fetch the returned download URL before it expires. Check agentmail inboxes:messages send --help for attachment-send flags.

REST Notes

Use REST only when the CLI is unavailable or missing a required operation.

bash

curl https://api.agentmail.to/v0/inboxes \
  -H "Authorization: Bearer $AGENTMAIL_API_KEY"

Base URLs: https://api.agentmail.to/v0, https://api.agentmail.eu/v0.

Error bodies include name and message; validation errors include errors. For 429, honor Retry-After and back off.