Quickstart

A working inbox for your agent in three steps. Pick how your agent runs; the steps below follow that choice.

For shell agents: Claude Code, Codex, Hermes, OpenClaw.

Set up

Runs from npx, nothing to install. help is the built-in reference.

npx --package=@atomicmail/agent-skill atomicmail help

Add the local server to your host's MCP config. Hosts that cannot run npx use the hosted server at https://mcp.atomicmail.ai/mcp.

{
  "mcpServers": {
    "atomicmail": {
      "command": "npx",
      "args": ["-y", "@atomicmail/mcp"]
    }
  }
}

Two base URLs. Auth errors carry hint and docs_url fields, so an agent can follow the flow from the API alone.

Auth: https://auth.atomicmail.ai
API:  https://api.atomicmail.ai

Register an inbox

Proof of work, no API key. The username is the permanent address and --watch is required, so ask the operator for both.

npx --package=@atomicmail/agent-skill atomicmail register \
  --username "myagent" \
  --watch scheduled

Call the register tool. Both inputs are required; watch is the operator's decision, not the agent's.

{ "username": "myagent", "watch": "scheduled" }

Request a challenge, solve the scrypt proof of work, open a session, then mint a capability token. Full request and response shapes are on the REST authentication page.

POST /api/v1/challenge    -> challenge JWT
POST /api/v1/session      -> session JWT      (1 hour)
POST /api/v1/capability   -> capability JWT   (2 minutes, JMAP bearer)

Send a message

Presets ship with the CLI. send_mail.json takes TO, SUBJECT and BODY.

npx --package=@atomicmail/agent-skill atomicmail jmap_request \
  --ops-file send_mail.json \
  --vars '{"TO":"alice@example.com","SUBJECT":"Hello","BODY":"Hi there"}'

Call jmap_request with the same preset.

{
  "ops_file": "send_mail.json",
  "vars": { "TO": "alice@example.com", "SUBJECT": "Hello", "BODY": "Hi there" }
}

Discover the session, then POST an Email/set + EmailSubmission/set batch with the capability JWT as bearer. The batch is the same one the wrappers use; see Raw JMAP requests and code examples.

curl https://api.atomicmail.ai/.well-known/jmap \
  -H "Authorization: Bearer $CAPABILITY_JWT"

Done: myagent@atomicmail.ai is live

Credentials are in ~/.atomicmail. Read the inbox with --ops-file list_inbox.json, and call help --topic cron for what --watch scheduled sets up on your host.

Where next

Agent flowInstall, register, watch, read, reactAuthenticationProof of work vs OAuth 2.0Who reads the inboxScheduled vs on-demand on your hostUsing your own domainDashboard verification and MX recordsZapierOAuth app with triggers and actionsn8nCommunity node with a polling triggerDifyMarketplace plugin, proof-of-work pathLangChainTools for JS and Python agentsHosted MCP serverOne URL for hosts that cannot run npxRaw JMAP requestsAny language, one endpoint, RFC 8620