Commands & Endpoints

Fresh 🌱

Copy-paste reference for the CLI, cURL, and the SDKs. Base URL: https://api.agentmail.to/v0. Auth header: Authorization: Bearer $AGENTMAIL_API_KEY.

Install

# Python
pip install agentmail
# Node / TypeScript
npm install agentmail
# CLI
npm install -g agentmail-cli

Onboarding

# Agent self sign-up (returns api_key, inbox_id, organization_id)
curl -X POST https://api.agentmail.to/v0/agent/sign-up \
  -H "Content-Type: application/json" \
  -d '{ "human_email": "you@example.com", "username": "my-agent" }'

# Verify OTP
curl -X POST https://api.agentmail.to/v0/agent/verify \
  -H "Authorization: Bearer $AGENTMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "otp_code": "123456" }'

# Who am I
curl https://api.agentmail.to/v0/auth/me -H "Authorization: Bearer $AGENTMAIL_API_KEY"

Inboxes

curl -X POST https://api.agentmail.to/v0/inboxes -H "Authorization: Bearer $AGENTMAIL_API_KEY" \
  -H "Content-Type: application/json" -d '{ "client_id": "my-inbox-v1" }'   # create
curl https://api.agentmail.to/v0/inboxes -H "Authorization: Bearer $AGENTMAIL_API_KEY"          # list
curl https://api.agentmail.to/v0/inboxes/<inbox_id> -H "Authorization: Bearer $AGENTMAIL_API_KEY" # get

Messages

# send
curl -X POST https://api.agentmail.to/v0/inboxes/<inbox_id>/messages/send \
  -H "Authorization: Bearer $AGENTMAIL_API_KEY" -H "Content-Type: application/json" \
  -d '{ "to": ["jane@example.com"], "subject": "Hi", "text": "Hello", "html": "<p>Hello</p>" }'

# reply
curl -X POST https://api.agentmail.to/v0/inboxes/<inbox_id>/messages/<message_id>/reply \
  -H "Authorization: Bearer $AGENTMAIL_API_KEY" -H "Content-Type: application/json" \
  -d '{ "text": "Thanks!", "html": "<p>Thanks!</p>" }'

# list / search
curl https://api.agentmail.to/v0/inboxes/<inbox_id>/messages -H "Authorization: Bearer $AGENTMAIL_API_KEY"

Endpoint map

Resource	Endpoints	Reference
Agent	/agent/sign-up, /agent/verify	Agent API
Auth	/auth/me	Auth API
API Keys	/api-keys (create/list/delete)	API Keys
Inboxes	/inboxes (CRUD)	Inboxes API
Messages	/inboxes/{id}/messages/*	Messages API
Threads	/inboxes/{id}/threads/*	Threads API
Drafts	/inboxes/{id}/drafts/*	Drafts API
Lists	/inboxes/{id}/lists/*	Labels & Lists
Events / Metrics	/inboxes/{id}/events, /metrics/query	Events & Metrics
Domains	/domains/*	Domains API
Webhooks	/webhooks/*	Webhooks API
WebSockets	/websockets	WebSockets API
Pods	/pods/*	Pods API
Organizations	/organizations/*	Organizations

Related

Quickstart · CLI integration · Troubleshooting · Limits