Prerequisites

• Node.js 22 or later (we use the built-in node:sqlite module — zero native compilation, no node-gyp headaches)
• brew (macOS) or apt (Linux) so the wizard can install Colima / Docker if you don't already have it

What `setup-email` actually exposes — read before connecting a relay

Heads-up for anyone running agenticmail setup-email (or telling Claude / Codex to do it for them). Once that command succeeds, your sub-agents are reachable from the public internet via Gmail / Outlook plus-addressing. This is the design — not a bug — but the implications surprise some operators:

- Every sub-agent has a publicly addressable inbox the moment setup-email finishes. Anyone who knows your relay address can hit yourrelay+<agentname>@gmail.com and the corresponding agent's AgenticMail inbox receives the message. Plus-addresses are publicly guessable (+secretary, +kepler, …) — don't treat them as a secret. - External mail wakes the dispatcher the same way internal @localhost mail does. When a new-mail event lands on a watched inbox, the dispatcher runs dedup + thread-cache + wake-budget checks and spawns a Claude Code (or Codex) worker turn. Source doesn't matter — bob@gmail.com and secretary@localhost are indistinguishable from the dispatcher's point of view. - The host bridge takes a different path. Mail to yourrelay+claudecode@gmail.com or yourrelay+codex@gmail.com doesn't spawn a worker — it goes to handleBridgeMail, which uses the host SDK's resume option to wake your last session headlessly. If that fails (session expired, host CLI not running), it falls through to the bridge-escalation email at setup_operator_email. So external mail to the bridge can wake your CLI / forward to your phone. - Watchout — spam wakes Claude / Codex turns. A scraper that finds astrumsphere+secretary@gmail.com in a leaked address book can drive worker turns at your expense. Throttles available, ordered from least invasive: 1. Let the wake-budget guard in dispatcher.handleEvent rate-limit naturally (default cap per minute per agent). 2. Add inbound spam rules at the relay layer so spam gets filtered before the SSE event publishes (built-in spam filter + tags can do this; see the Security section below). 3. For agents that should be internal-only, set metadata.host to a value no dispatcher matches, or stop the relay's IMAP poller from publishing on that inbox.

Two install paths

Autonomous install (recommended for most users)

```bash

Option A — one-liner (does the npm install + bootstrap for you, plus a Node 22+ preflight)

curl -fsSL https://raw.githubusercontent.com/agenticmail/agenticmail/main/install.sh | bash

Want non-interactive setup? (env-piped, AI-assistant-friendly)

Same setup, no prompts — secrets ride in via env vars. Useful for Claude / Codex / scripted installs:

```bash

Manual tunnel control (not usually needed — setup-phone opens one for you)

agenticmail tunnel start # cloudflared quick-tunnel agenticmail tunnel url # prints the *.trycloudflare.com URL agenticmail tunnel stop ```

Setup

Add to your MCP client configuration (e.g., .mcp.json or project settings):

{
  "mcpServers": {
    "agenticmail": {
      "command": "npx",
      "args": ["agenticmail-mcp"],
      "env": {
        "AGENTICMAIL_API_URL": "http://127.0.0.1:3829",
        "AGENTICMAIL_API_KEY": "ak_your_agent_key"
      }
    }
  }
}

Picking the right install path

Quick Start

Option B — equivalent, manually

npm install -g @agenticmail/cli agenticmail bootstrap

Either path: zero prompts. The pipeline:

1. **`agenticmail setup --yes`** — auto-installs Colima + Docker if missing, starts the Stalwart mail server, generates your master key, creates a default "secretary" agent. **Skips external email/SMS setup** (those need user-owned credentials; add them later if you want).
2. **`agenticmail service install`** — registers a launchd plist (macOS) / systemd unit (Linux) so the API auto-starts on boot, and starts it now.
3. Waits for `GET /api/agenticmail/health` to come up on the configured port (default `http://127.0.0.1:3829`).
4. **`agenticmail claudecode`** — wires the Claude Code integration in if you have Claude Code installed (idempotent / no-op otherwise).

After this, you have a fully working local AgenticMail with internal multi-agent coordination over `*@localhost`. Add an external Gmail relay or your own domain anytime with `agenticmail setup` (interactive).

#### Interactive install

The wizard walks you through everything: dependency checks, master key generation, mail-server start, optional Gmail relay or custom domain, optional SMS setup, optional realtime voice (OpenAI API key), optional phone calling (pick 46elks or Twilio and enter that carrier's credentials), optional Telegram channel (bot token + chat link), and optional OpenClaw integration. Every optional step is skippable and re-runnable any time. With --yes / --non-interactive all the optional steps are skipped with safe defaults.

The new optional steps in detail:

• Realtime voice — paste an OpenAI API key to enable live spoken phone calls (the realtime voice bridge). Without it, phone missions still place and track call-control calls; only the spoken-conversation bridge is unavailable. The key is stored as openaiApiKey in ~/.agenticmail/config.json (file mode 0600).
• Phone calling — pick your carrier (46elks or twilio), enter that carrier's credentials (46elks API username/password, or Twilio Account SID/Auth Token), a caller number, and a public HTTPS webhook base URL. The webhook secret is auto-generated if you don't supply one. Persisted to the agent's phone-transport config.
• Telegram channel — paste a bot token from @BotFather and your chat id. The token is verified with Telegram before it's stored; the channel comes up in poll mode and agenticmail start auto-spawns a standalone bridge service that wakes the agent on inbound DMs with the full MCP toolset (memory, send_email, call_phone, …) available.

CLI Commands

AgenticMail includes a full CLI for managing your server. All commands are available via agenticmail <command> or npx @agenticmail/cli@latest <command>.

Or via API:

curl -X POST http://127.0.0.1:3829/api/agenticmail/gateway/relay \ -H "Authorization: Bearer mk_your_master_key" \ -H "Content-Type: application/json" \ -d '{ "provider": "gmail", "email": "you@gmail.com", "password": "xxxx xxxx xxxx xxxx" }' ```

Requirements: - Gmail: App password (not your regular password) - Outlook: App password from Microsoft account security settings

API Overview

All endpoints are under /api/agenticmail. Authentication via Authorization: Bearer <key> header.

Two key types: - Master key (mk_...) — full admin access (create/delete agents, approve blocked emails, gateway config) - Agent key (ak_...) — scoped to one agent (read own inbox, send email, manage own drafts/contacts/etc.)

Key Endpoints

Plus endpoints for drafts, contacts, tags, rules, signatures, templates, scheduled emails, spam management, batch operations, domains, and agent deletion/cleanup.

See the API package README for complete endpoint documentation.

---

Integrations

• MCP server — 90+ tools for any MCP-compatible AI client
• OpenClaw plugin — 80+ tools with skill definition and system prompt guidelines
• REST API — 75+ endpoints, OpenAPI-style, Bearer token auth
• SSE events — real-time inbox notifications via Server-Sent Events
• Interactive CLI — 44 shell commands with arrow key navigation, body previews, retry logic
• Self-updating — agenticmail update or /update in shell, with OpenClaw compatibility check

---

Integration Commands

Packages

This is a TypeScript monorepo. Seven packages, each shipped to npm independently.

Plugin folders (host marketplace manifests, separate from npm packages):

Dependency graph:

@agenticmail/cli ──────> @agenticmail/api ────> @agenticmail/core
@agenticmail/mcp       (standalone — HTTP calls to API)
@agenticmail/claudecode (peer-dep on @anthropic-ai/claude-agent-sdk)
@agenticmail/codex      (peer-dep on @openai/codex-sdk)
@agenticmail/openclaw   (standalone — HTTP calls to API)

---

MCP Integration

The MCP server exposes 80+ tools to any MCP-compatible AI client via stdio transport.

Host Integrations

AgenticMail is host-agnostic at the protocol level (it's just SMTP/IMAP/HTTP/MCP under the hood), but each agentic CLI host expects its config + hooks + subagent definitions in a slightly different shape. We ship one host integration package per supported host. Each one:

1. Registers the AgenticMail MCP server in the host's config so the model can see all 100 tools.
2. Surfaces every AgenticMail account as a native sub-agent the model can dispatch to.
3. Wires up the host's lifecycle hooks (SessionStart, UserPromptSubmit, Stop) so the agent gets a fresh-mail digest and capabilities preamble at the right moments.
4. Runs a long-lived dispatcher daemon that watches every account's inbox via SSE and spawns a one-shot model turn whenever new mail or a task arrives — so agents wake on each other's replies automatically without polling.