接入你的智能体
發布者自己的指令。不是 PlugMCP 端點。
用我們的金鑰與日誌託管一份副本。
npx -y @agenticmail/[email protected]Claude Code 沒有本機指令的安裝連結。複製下方指令並在終端機中執行。
AGENTICMAIL_API_KEY=<secret> AGENTICMAIL_MASTER_KEY=<secret> AGENTICMAIL_API_URL=<value> claude mcp add io.github.agenticmail-mcp -- npx -y @agenticmail/mcp@0.5.59在終端機中執行。
{ "mcpServers": { "io.github.agenticmail-mcp": { "command": "npx", "args": [ "-y", "@agenticmail/[email protected]" ], "env": { "AGENTICMAIL_API_KEY": "<secret>", "AGENTICMAIL_MASTER_KEY": "<secret>", "AGENTICMAIL_API_URL": "<value>" } } }}claude_desktop_config.json
遠端 URL 還是本機指令？ 兩種安裝方式的差異
來自發布者
Are you an AI agent reading this on behalf of a human?
Your human asked you to install / set up AgenticMail. Pick either of these and then tell them to restart Claude Code:
# Option A — one-line installer (recommended) curl -fsSL https://raw.githubusercontent.com/agenticmail/agenticmail/main/install.sh | bash # Option B — manual two-command install npm install -g @agenticmail/cli@latest agenticmail bootstrap
Real email and SMS for AI agents — send mail, receive verification codes, drive a real inbox.
Zero prompts, ~2 minutes, fully autonomous. For the full runbook (verification, common failures, repo conventions if you're modifying the code), see AGENTS.md — the agents.md file at this repo's root.
Structured RPC vs. Text-Based Sub-Agent Orchestration — A comparative analysis of inter-agent communication paradigms. Demonstrates why AgenticMail's call_agent achieves 53× faster response times than conventional sub-agent spawning, and introduces the concept of the Conversational Fallacy in multi-agent AI systems. [PDF] [Source]
A local, opt-in media / video-editing toolset for AgenticMail agents.
media_tts / media_tts_voices (Edge text-to-speech), media_image_edit, media_video_edit, media_audio_edit, media_info, media_video_understand, media_voice_clone, and media_capabilities. Available as MCP media_* tools and OpenClaw agenticmail_media_* tools, both thin clients of new /media/* API routes over a core MediaManager.media block on /health and the media_capabilities tool surface what is available.execFile with an argument array — no shell, no string interpolation. Untrusted input paths are validated (no control characters, no leading-dash flag-injection, must exist); numeric options are clamped; every call carries a bounded timeout and output buffer; output files land only inside the configured media directory.Twilio joins 46elks as a phone transport provider.
PhoneTransportProvider is now 46elks or twilio — chosen at phone setup. 46elks behaviour is unchanged; Twilio is at full parity (outbound call-control + realtime voice).Calls.json REST API, TwiML webhooks, status-callback cost tracking. Inbound webhooks are verified with the X-Twilio-Signature header (HMAC-SHA1, timing-safe, fail-closed) on top of the per-mission token.RealtimeVoiceBridge was generalised behind a RealtimeTransportAdapter seam — one bridge serves both carriers, function-calling / barge-in / transcript logic written once. Twilio audio is G.711 µ-law @ 8 kHz and the OpenAI session uses audio/pcmu, so a Twilio call needs no transcoding. A <Connect><Stream> connects to /api/agenticmail/calls/twilio-stream.1038 tests pass; full build green. The live Twilio ↔ OpenAI call path still needs an operator smoke-test before the npm publish.
Realtime voice tools + a Telegram channel.
session.tools; RealtimeVoiceBridge dispatches the model's function calls through an injected ToolExecutor, returns function_call_output, and keeps the phone line warm during slow tools with a safety-net timeout + an in-flight call cap.ask_operator — human-in-the-loop on a live call. The agent records an operator query on the mission, notifies the operator (channel-agnostic; default email), polls up to ~5 min, and resumes with the answer. If the caller hangs up while a query is pending, the mission is flagged for callback-on-disconnect — once the operator answers, it re-dials with a continuity task.web_search (keyless DuckDuckGo, results fenced as untrusted content), recall_memory (the agent's universal memory), get_datetime. Plus agent-key-scoped operator-query API endpoints.ask_operator notifications and approvals.operatorEmail; Telegram bot tokens are encrypted at rest and redacted from logs; new SQL is parameterized.996 tests pass; full build green. The live OpenAI ⇄ 46elks call path and live Telegram delivery still need an operator smoke-test before the npm publish.
Realtime voice + OpenClaw memory.
RealtimeVoiceBridge (@agenticmail/core) wires an OpenAI Realtime (gpt-realtime) session to a 46elks realtime-media WebSocket: caller audio (PCM16 @ 24 kHz) is relayed to OpenAI, synthesised speech comes back as response.output_audio.delta and is relayed to 46elks, server-side VAD handles turn-taking, and caller barge-in fires a 46elks interrupt. 46elks streams a call to the new /api/agenticmail/calls/realtime WebSocket endpoint, which matches the connection to its mission by 46elks callid and runs the bridge. Set OPENAI_API_KEY (env or config.json) to enable it.generateMemoryContext() and folded into the Realtime session instructions — the model is told to treat it as its own long-term knowledge, so the call is continuous with everything the agent has learned elsewhere.agenticmail_memory, agenticmail_memory_reflect, agenticmail_memory_context, and agenticmail_memory_stats bring the universal per-agent memory to OpenClaw agents — 69 → 73 tools.The end-to-end voice path needs a live OPENAI_API_KEY and a provisioned 46elks websocket number — the bridge logic, memory injection, and the WebSocket upgrade/auth glue are unit-tested with mocked sockets, but the live call must be smoke-tested by the operator.
The universal memory release. Every agent now has a persistent, evolving memory — categorised, confidence-decaying, BM25F-searchable knowledge that survives across every conversation, the way a human employee learns on the job.
AgentMemoryManager (@agenticmail/core) — CRUD, text recall, 9 memory categories, importance levels, confidence that decays for unaccessed entries, access tracking, pruning, and generateMemoryContext() which ranks + renders memory as a markdown block for prompt injection. Backed by a zero-dependency BM25F search index and an agent_memory table. Ported from the AgenticMail Enterprise memory engine, org-stripped — memory is personal to each agent./memory (set / list / search / get / delete), /memory/reflect, /memory/context, /memory/stats. Every endpoint is scoped to the authenticated agent; an agent can only ever read or write its own memory.memory, memory_reflect, memory_context, memory_stats so any MCP client can give its agent durable memory.agent_memory rows; no orphaned memory is left behind.The visibility release — closes every "what just happened?" gap from 0.9.0.
(agent, thread) spawns instantly; bursts within the window collapse into one trailing wake.check_activity now shows dispatcher: { state: 'alive' | 'unhealthy' | 'missing', uptimeMs, channels, coalesceQueueSize, ... }. The host can finally answer "is the dispatcher up?" in one query.check_activity surfaces the last 100. No more "did my mail land? did it skip?" guessing.wake_on_cc: false flag. Coder agents can register a preference: never wake when only on Cc, regardless of sender. PATCH /accounts/:id/wake-on-cc.deriveDefaultWakeList. Senders using "Vesper <vesper@localhost>" form no longer fall through to "no allowlist → wake everyone".to: line).docs/wake-patterns.md documents every wake shape + 5 recommended patterns.The wake-context release. Multi-agent thread cost goes from linear-in-thread-length to roughly flat.
read_email prior history. New MCP tools save_thread_memory and get_thread_id.wake default flipped from "everyone CC'd" → "To: only". Mirrors the email convention: To is for action, CC is for awareness. CC'd local agents still receive the mail in their inbox but don't get a Claude turn unless explicitly named in wake. Opt back into the old behaviour with wake: 'all'.(agent, thread), multiple wake events collapse into ONE Claude turn. A burst of 4 quick replies becomes one Claude wake that sees all four in a coalesced batch prompt. Wake-budget charges once. Configurable via wakeCoalesceMs.Together these eliminate the "wake-thrash" failure mode where an agent fired 4 near-identical status reports because a designer sent 4 replies in 2 minutes.
call_agent / POST /tasks/assign accept an outputSchema (JSON Schema, draft-7 subset). submit_result validates against it; mismatches return 400 with the validator errors so the worker can retry with a corrected shape.All Mail folder hides itself on servers that don't have one (Stalwart, most non-Gmail). Select-all checkbox now wires through.\Flagged flag via the new POST /mail/messages/:uid/star endpoint. Backed by MailReceiver.setStarred in @agenticmail/core. Optimistic UI; revert on failure.Sent Items not Sent). Now auto-discovered per agent and matched against every common server convention (Stalwart, Gmail, Outlook, macOS Mail)./mail/digest?folder=… everywhere instead of /mail/inbox (no preview) + /mail/folders/:folder (no preview).#/folder/<id> (sent, drafts, spam, …). Back/forward works, URLs are shareable, refresh stays put.~/.agenticmail/worker-logs/<id>.log, posts heartbeats every 30 s, and runs in its own isolated cwd so parallel agents don't clobber each other's output. New MCP tool tail_worker to read a running worker's log live; check_activity now shows last tool used, turn count, and a stale flag (no auto-eviction).decision: 'block' at turn boundaries when the bridge inbox has new mail, forcing Claude to continue with the new-mail summary in context. Closes the follow-up that 0.8.23 filed.agenticmail-mail-hook: command not found errors — hook is now registered with an absolute path resolved at install time. Resilient to any $PATH configuration; old installs auto-heal on the next agenticmail claudecode run.(m.flags ?? []).includes is not a function crash gone; sidebar folders (Sent / Drafts / Spam / Trash) now load their real IMAP mailboxes instead of all hitting /mail/inbox; Cmd+C no longer pops the compose modal; full mobile-responsive layout with an off-canvas sidebar.@ mark from branding/ now ship bundled and render as the host avatar + topbar / favicon.wake: ["alice", "bob"] on send_email / reply_email / forward_email / template_send / manage_drafts(send) tells the dispatcher to give a Claude turn only to named agents. The other CC'd recipients still receive the mail but stay asleep. Cuts token cost on large threads by ~10× when used.[FINAL], [DONE], [CLOSED], or [WRAP] in a subject tells the dispatcher this thread is done; no more wakes on any reply.check_activity MCP tool — see which agents the dispatcher has woken right now, how long they've been running, and a preview of recent completions. The answer to "did the agent I just emailed actually start working?">>>>).batch_mark_read({ uids: "[1,2,3]" }) and other common stringification mistakes now just work; coerced before validation.See CHANGELOG.md for the full release history.
AgenticMail is a self-hosted communication platform purpose-built for AI agents. It runs a local Stalwart mail server via Docker, integrates SMS/phone access via Google Voice or 46elks, exposes a REST API with 75+ endpoints, ships a lightweight Gmail-style web UI for human oversight, and works with any MCP-compatible AI client and OpenClaw via plugin. Each agent gets its own email address, phone number, inbox, and API key.
AI agents need to communicate with the real world. Email is the universal communication protocol — every person and business has an email address. AgenticMail bridges the gap between AI agents and email by providing:
gpt-realtime) session so an agent can hold a live two-way conversation, with its persistent memory folded into the call.call_agent replaces basic sub-agent spawning with auto mode detection, dynamic timeouts, runtime tool discovery, and async execution for long-running tasks.agenticmail update checks npm, verifies OpenClaw compatibility, and updates both packages automatically.@localhostYou can watch the whole team work in one place with agenticmail shell:
That's a real multi-agent thread captured in the REPL — the host kicked off one email, Solène verified the file Cassian shipped to disk, and every step is sitting there as ordinary mail. No custom orchestration code. Type agenticmail shell any time you want to see what your agents have been up to.
[email protected]. Setup takes 2 minutes.[email protected] with full DKIM signing, SPF, and DMARC records.
@domain email alias for all existing agentssetup-email actually exposes — read before connecting a relayHeads-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:
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.@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 — [email protected] and secretary@localhost are indistinguishable from the dispatcher's point of view.[email protected] or [email protected] 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.[email protected] in a leaked address book can drive worker turns at your expense. Throttles available, ordered from least invasive:
wake-budget guard in dispatcher.handleEvent rate-limit naturally (default cap per minute per agent).metadata.host to a value no dispatcher matches, or stop the relay's IMAP poller from publishing on that inbox.POST /mail/pending/:id/approve)RealtimeVoiceBridge bridges a phone mission to an OpenAI Realtime (gpt-realtime) session so an agent can actually talk on the call, not just place itRealtimeVoiceBridge is generalised behind a RealtimeTransportAdapter so both run through one bridge. 46elks streams to /api/agenticmail/calls/realtime (PCM16 @ 24 kHz); Twilio Media Streams connects a <Connect><Stream> to /api/agenticmail/calls/twilio-stream (G.711 µ-law @ 8 kHz — OpenAI audio/pcmu, no transcoding). Server-side VAD for turn-taking, caller barge-in relayed to the carrier.callid, authenticates the connection token, and persists the conversation transcript to the missionOPENAI_API_KEY to enable; without it, phone missions still place and track calls (call-control only)ask_operator (human-in-the-loop — pause, ask the operator, resume, or call back on disconnect), web_search, recall_memory, get_datetimeX-Telegram-Bot-Api-Secret-Token compare; uniform 403 on mismatchask_operator notifications and approvals, so a phone agent can reach you on Telegram mid-callmedia_tts, media_tts_voices, media_image_edit, media_video_edit, media_audio_edit, media_info, media_video_understand, media_voice_clone, plus media_capabilitiesmedia_capabilities (or read the /health media block) to see what is availableexecFile with an argument array (never a shell); untrusted input paths are validated (no control characters, no leading-dash flag-injection, must exist) and output files land only inside the configured media directorycritical entries never decay; low-confidence and expired entries are prunedgenerateMemoryContext() renders a ranked markdown block for injection into agent prompts and realtime voice sessions/memory* REST endpoints, MCP tools (memory, memory_reflect, memory_context, memory_stats), and OpenClaw tools (agenticmail_memory*)agenticmail update or /update in shell, with OpenClaw compatibility check ┌──────────────────────────────────────────────────┐
│ AgenticMail │
│ │
AI Client ─MCP─> │ @agenticmail/mcp (100 tools, stdio transport)│
│ │ │
OpenClaw ─────> │ @agenticmail/openclaw (89 tools, plugin) │
│ │ │
HTTP clients──> │ ▼ │
│ @agenticmail/api (Express, 75+ endpoints) │
│ ├── Authentication (master key + agent keys) │
│ ├── Rate limiting (per-endpoint) │
│ ├── SSE streaming (real-time inbox events) │
│ └── Spam filter + Outbound guard │
│ │ │
│ ▼ │
│ @agenticmail/core (SDK layer) │
│ ├── AccountManager (CRUD agents in Stalwart) │
│ ├── MailSender (SMTP, nodemailer) │
│ ├── MailReceiver (IMAP, imapflow) │
│ ├── InboxWatcher (IMAP IDLE → events) │
│ ├── GatewayManager (relay + domain routing) │
│ │ ├── RelayGateway (Gmail/Outlook) │
│ │ ├── CloudflareClient (DNS, tunnels, etc) │
│ │ ├── TunnelManager (cloudflared) │
│ │ ├── DNSConfigurator (MX, SPF, DKIM) │
│ │ └── DomainPurchaser (Registrar API) │
│ ├── StalwartAdmin (mail server management) │
│ ├── EmailSearchIndex (FTS5 full-text search) │
│ └── Storage (SQLite + migrations) │
│ │ │
│ ▼ │
│ Stalwart Mail Server (Docker container) │
│ ├── SMTP (port 587) — submission │
│ ├── SMTP (port 25) — inbound delivery │
│ ├── IMAP (port 143) — mailbox access │
│ └── HTTP (port 8080) — admin API │
└──────────────────────────────────────────────────┘
│ │
┌─────────────┘ └──────────────┐
▼ ▼
Relay Mode Domain Mode
┌──────────────────┐ ┌──────────────────────┐
│ Gmail / Outlook │ │ Cloudflare │
│ IMAP polling │ │ ├── DNS zone │
│ SMTP relay │ │ ├── Tunnel │
│ Sub-addressing │ │ ├── Email Routing │
│ (+agent@gmail) │ │ ├── Email Worker │
└──────────────────┘ │ └── Registrar │
└──────────────────────┘
Sending email (relay mode):
POST /mail/send with recipient, subject, body[email protected]Sending email (domain mode):
POST /mail/sendagent@localhost → [email protected]Receiving email (relay mode):
X-AgenticMail-Relay: inbound header added for identificationReceiving email (domain mode):
[email protected]/api/agenticmail/mail/inboundnode: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# 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
# Option B — equivalent, manually
npm install -g @agenticmail/cli
agenticmail bootstrap
Either path: zero prompts. The pipeline:
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).agenticmail service install — registers a launchd plist (macOS) / systemd unit (Linux) so the API auto-starts on boot, and starts it now.GET /api/agenticmail/health to come up on the configured port (default http://127.0.0.1:3829).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).
npm install -g @agenticmail/cli
agenticmail setup
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:
openaiApiKey in ~/.agenticmail/config.json (file mode 0600).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.@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.Same setup, no prompts — secrets ride in via env vars. Useful for Claude / Codex / scripted installs:
# Email
GMAIL_PASSWORD=… agenticmail setup-email <gmail-address>
# Twilio outbound calls (auto-opens a free Cloudflare quick-tunnel if you
# don't have a public HTTPS URL — no Cloudflare account required)
TWILIO_ACCOUNT_SID='<sid>' TWILIO_AUTH_TOKEN='<token>' \
AGENTICMAIL_PHONE_NUMBER='<E.164>' \
agenticmail setup-phone --provider twilio
# Telegram (bridge auto-spawns on next `agenticmail start`)
TELEGRAM_BOT_TOKEN='<from @BotFather>' TELEGRAM_CHAT_ID='<your chat id>' \
agenticmail setup-telegram
# 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
Yes. AgenticMail works in local-only mode — agents email each other at *@localhost through the bundled Stalwart server with full RFC-822 routing, threading, attachments, and search. That's all the Claude Code multi-agent flow needs. The external Gmail/domain relay is optional and only matters when you want agents to send mail to the public internet.
~/.agenticmail/config.json, file mode 0600)node:sqlite — Node 22+ built-in, no native compilation, no prebuilt binaries needed)import { AgenticMailClient } from '@agenticmail/cli';
const client = new AgenticMailClient({
apiUrl: 'http://127.0.0.1:3829',
apiKey: 'ak_your_agent_api_key',
});
// Send an email
await client.send({
to: '[email protected]',
subject: 'Hello from my AI agent',
text: 'This email was sent by an AI agent using AgenticMail.',
});
// Check inbox
const inbox = await client.listInbox(10);
for (const msg of inbox) {
console.log(`${msg.from} — ${msg.subject}`);
}
// Read a specific email
const email = await client.readMessage(inbox[0].uid);
console.log(email.text);
agenticmail> /send
To: [email protected]
Subject: Test email
Body: Hello from the AgenticMail shell!
Email sent! Message ID: <abc123@localhost>
curl -X POST http://127.0.0.1:3829/api/agenticmail/mail/send \
-H "Authorization: Bearer ak_your_agent_key" \
-H "Content-Type: application/json" \
-d '{
"to": "[email protected]",
"subject": "Hello",
"text": "Sent via the AgenticMail API."
}'
AgenticMail includes a full CLI for managing your server. All commands are available via agenticmail <command> or npx @agenticmail/cli@latest <command>.
AgenticMail installs a system service so it automatically starts when your computer boots. On macOS this is a LaunchAgent; on Linux it's a systemd user service.
What happens on reboot:
restart: unless-stopped in Docker)If the API server crashes, the system service automatically restarts it.
Server logs are stored in ~/.agenticmail/logs/:
server.log — API server stdoutserver.err.log — API server stderrstartup.log — Boot sequence log (Docker wait times, Stalwart checks)AgenticMail supports two modes for sending/receiving real internet email:
Use your existing Gmail or Outlook account as a relay. No domain purchase needed. Setup takes under 2 minutes.
How it works:
[email protected][email protected] and delivers them to the agent's local mailbox+ sub-addressing routes replies back to the right agentSetup:
# In the interactive shell:
agenticmail> /relay
# 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": "[email protected]",
"password": "xxxx xxxx xxxx xxxx"
}'
Requirements:
Full custom domain with Cloudflare. Agents send from [email protected] with proper email authentication.
What gets configured automatically:
v=spf1 include:_spf.mx.cloudflare.net ~all)v=DMARC1; p=quarantine)@domain email aliases for all existing agentsSetup:
curl -X POST http://127.0.0.1:3829/api/agenticmail/gateway/domain \
-H "Authorization: Bearer mk_your_master_key" \
-H "Content-Type: application/json" \
-d '{
"cloudflareToken": "your_cf_api_token",
"cloudflareAccountId": "your_cf_account_id",
"domain": "yourdomain.com",
"gmailRelay": {
"email": "[email protected]",
"appPassword": "xxxx xxxx xxxx xxxx"
}
}'
Cloudflare API token permissions needed:
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)
All endpoints are under /api/agenticmail. Authentication via Authorization: Bearer <key> header.
Two key types:
mk_...) — full admin access (create/delete agents, approve blocked emails, gateway config)ak_...) — scoped to one agent (read own inbox, send email, manage own drafts/contacts/etc.)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.
The MCP server exposes 80+ tools to any MCP-compatible AI client via stdio transport.
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"
}
}
}
}
For desktop AI applications, add the same configuration to your app's MCP config file (check your app's documentation for the file location).
Once connected, your AI can:
list_inboxsend_emailreply_emailsearch_emailsmanage_draftscheck_taskscall_agentSee the MCP package README for the full tool list.
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:
SessionStart, UserPromptSubmit, Stop) so the agent gets a fresh-mail digest and capabilities preamble at the right moments.Both integrations share the same dispatcher architecture (per-agent serialization, wake-coalesce, wake-budget, restart recovery, capabilities preamble). The host-specific bits are: config-file format (JSON vs TOML), subagent definition syntax (markdown+frontmatter vs TOML heredoc), and the SDK we drive workers through (@anthropic-ai/claude-agent-sdk vs @openai/codex-sdk).
The mail layer is the lingua franca. An agent running under Claude Code can email an agent running under Codex (or vice versa) using the exact same send_email({ to, cc, wake }) MCP tool — the message lands in the target's inbox, the target's host-specific dispatcher picks it up, spawns the right kind of turn (Claude or Codex), and the agent replies-all to the thread. From the sender's perspective there's no API difference between "my teammate runs under the same host as me" and "my teammate runs under a different host." That's the whole point of routing through email instead of host-native peer messaging.
Already have OpenClaw? Two steps:
# Step 1 — Install AgenticMail globally and run the setup wizard
npm install -g @agenticmail/cli && agenticmail setup
# Step 2 — Connect AgenticMail to your OpenClaw instance
agenticmail openclaw
That's it. The global install gives you the agenticmail command. The openclaw command will start the mail server, create an agent, and merge the plugin config into your openclaw.json automatically. Your OpenClaw agent now has its own email address.
If you prefer to configure manually, add to ~/.openclaw/openclaw.json:
{
"plugins": {
"agenticmail": {
"enabled": true,
"config": {
"apiUrl": "http://127.0.0.1:3829",
"apiKey": "ak_your_agent_key",
"masterKey": "mk_your_master_key"
}
}
}
}
The plugin survives OpenClaw updates — plugin configuration lives in user config (~/.openclaw/openclaw.json), not in the OpenClaw source directory.
Use /chat in the AgenticMail shell to talk directly to your OpenClaw agent in real-time:
╭───────────────────────────────────────────────╮
│ ❯ what's the weather in NYC? │
╰───────────────────────────────────────────────╯
You 👤
╭──────────────╮
│ what's the │
│ weather in │
│ NYC? │
╰──────────────╯
🎀 Fola
╭──────────────────────────────────────╮
│ Currently 42°F and cloudy in NYC. │
╰──────────────────────────────────────╯
\ + Enter for new lines)The call_agent tool intelligently spawns sub-agents:
call_agent(async=true) for long-running tasks. The caller polls /tasks/assigned for completion; the assigned agent emails the result back to the caller when it has email capability enabled. In a localhost-only / no-relay setup the result still lands in the caller's local mailbox, so check /mail/inbox if you don't see an SMTP delivery.See the OpenClaw package README for the full tool list.
The CLI includes a full-featured interactive shell with 44 commands:
agenticmail> /inbox
★ 1 [email protected] Project Update 2m ago
2 [email protected] Re: Budget Review 1h ago
3 [email protected] [repo] New issue #42 3h ago
─────────────────────────────────────────────────
Page 1/3 ─ [←] prev [→] next [v] toggle previews [Esc] back
Use ↑↓ arrow keys to select, Enter to read inline
Key features:
v)Enter)★)←/→ navigationEmail: /inbox /send /read /reply /forward /search /delete /save
/thread /unread /archive /trash
Organize: /folders /contacts /drafts /signature /templates /schedule /tag
Agents: /agents /switch /deleteagent /deletions
Security: /spam /rules /pending
Gateway: /relay /digest /setup /status /openclaw
System: /help /clear /exit
Every outgoing email is scanned before sending. The guard detects:
When sensitive data is detected:
pending_outbound tablePOST /mail/pending/:id/approve or /reject) or by replying to the notification emailInbound emails are scored against rule-based patterns:
@localhost from, external replyTo) are always treated as external# === Required ===
AGENTICMAIL_MASTER_KEY=mk_your_key # Master API key (generate: openssl rand -hex 32)
# === Stalwart Mail Server ===
STALWART_ADMIN_USER=admin # Stalwart admin username
STALWART_ADMIN_PASSWORD=changeme # Stalwart admin password
STALWART_URL=http://localhost:8080 # Stalwart HTTP admin URL
# === SMTP/IMAP (local Stalwart) ===
SMTP_HOST=localhost # SMTP host
SMTP_PORT=587 # SMTP submission port
IMAP_HOST=localhost # IMAP host
IMAP_PORT=143 # IMAP port
# === Optional ===
AGENTICMAIL_API_PORT=3829 # API server port (default: 3829 — chosen to
# avoid 3000/3100/3200/3300/4000/5000/8000/8080
# which are all common dev-tool defaults)
AGENTICMAIL_API_HOST=127.0.0.1 # API bind host (default: 127.0.0.1; loopback only)
AGENTICMAIL_DATA_DIR=~/.agenticmail # Data directory for SQLite DB and config
# === Realtime Voice (optional) ===
OPENAI_API_KEY=sk-... # Enables the realtime voice bridge — bridges a
# phone mission to an OpenAI Realtime session.
# Without it, calls are call-control only.
# === Gateway: Relay Mode ===
RELAY_PROVIDER=gmail # gmail or outlook
[email protected] # Your email address
RELAY_PASSWORD=xxxx xxxx xxxx xxxx # App password
# === Gateway: Domain Mode ===
CLOUDFLARE_API_TOKEN=your_token # Cloudflare API token
CLOUDFLARE_ACCOUNT_ID=your_account_id # Cloudflare account ID
AGENTICMAIL_DOMAIN=yourdomain.com # Your domain
AGENTICMAIL_INBOUND_SECRET=your_secret # Shared secret for Email Worker
# === Gmail SMTP Relay (domain mode outbound) ===
[email protected] # Gmail address for outbound relay
GMAIL_RELAY_APP_PASSWORD=xxxx xxxx xxxx # Gmail app password
# === Debug ===
# AGENTICMAIL_DEBUG=1 # Enable verbose per-message logging
# docker-compose.yml (included in repo)
services:
stalwart:
image: stalwartlabs/stalwart:latest
container_name: agenticmail-stalwart
ports:
- "8080:8080" # HTTP Admin + JMAP
- "587:587" # SMTP Submission
- "143:143" # IMAP
- "25:25" # SMTP Inbound
volumes:
- stalwart-data:/opt/stalwart
- ~/.agenticmail/stalwart.toml:/opt/stalwart/etc/stalwart.toml:ro
restart: unless-stopped
AgenticMail stores all state in a SQLite database at ~/.agenticmail/agenticmail.db. As of @agenticmail/[email protected] we use Node's built-in node:sqlite module (stable since Node 22) instead of better-sqlite3. The migration removed all native compilation from the install path — no node-gyp, no prebuilt-binary version-mismatch issues, no Python prerequisites. The on-disk database format is unchanged (it's still SQLite 3), so existing ~/.agenticmail/agenticmail.db files continue to work without migration.
Tables:
agents — agent accounts (name, email, API key, metadata)gateway_config — relay or domain mode configurationpending_outbound — blocked emails awaiting approvaldelivered_messages — deduplication tracking for inbound relayspam_log — spam scoring historyagent_tasks — inter-agent task assignmentsemail_rules — per-agent email filtering rulescontacts, drafts, signatures, templates, scheduled_emails, tagsgit clone https://github.com/agenticmail/agenticmail.git
cd agenticmail
npm install
docker compose up -d
npm run build
npm test
agenticmail/
├── agenticmail/ # CLI facade package (npm: agenticmail)
│ └── src/
│ ├── cli.ts # CLI entry point (setup, start, status)
│ ├── shell.ts # Interactive REPL (44 commands)
│ └── index.ts # Re-exports from @agenticmail/core
├── packages/
│ ├── core/ # @agenticmail/core
│ │ └── src/
│ │ ├── accounts/ # Agent CRUD, roles, deletion
│ │ ├── mail/ # Sender, receiver, parser, spam filter, outbound guard
│ │ ├── inbox/ # IMAP IDLE watcher
│ │ ├── gateway/ # Relay, Cloudflare, DNS, tunnel, domain purchase
│ │ ├── stalwart/ # Stalwart admin API client
│ │ ├── storage/ # SQLite database, migrations, search index
│ │ ├── domain/ # Domain management
│ │ └── setup/ # Dependency checker, installer
│ ├── api/ # @agenticmail/api
│ │ └── src/
│ │ ├── app.ts # Express app factory
│ │ ├── routes/ # 8 route modules (mail, accounts, events, etc.)
│ │ └── middleware/ # Auth, rate limiting, error handling
│ ├── mcp/ # @agenticmail/mcp
│ │ └── src/
│ │ ├── index.ts # MCP server entry (stdio transport)
│ │ ├── tools.ts # 80+ tool definitions and handlers
│ │ └── resources.ts
│ └── openclaw/ # @agenticmail/openclaw
│ ├── index.ts # Plugin entry, system prompt
│ ├── src/tools.ts # 89 tool definitions and handlers
│ └── skill/ # SKILL.md, reference docs, scripts
├── docker-compose.yml # Stalwart mail server
├── .env.example # Environment variable template
└── package.json # Workspace root
# Build all packages
npm run build
# Build a single package
cd packages/core && npx tsup src/index.ts --format esm --dts --clean
# Run all tests
npm test
# Run tests for a specific package
cd packages/core && npx vitest run
Publish in dependency order:
cd packages/core && npm publish
cd packages/api && npm publish
cd packages/mcp && npm publish
cd packages/openclaw && npm publish
cd agenticmail && npm publish
All scoped packages have "publishConfig": { "access": "public" } configured.
See CONTRIBUTING.md for development guidelines.
AgenticMail collects anonymous usage statistics to help improve the product. We track:
We never collect API keys, email content, addresses, or any personal information.
Opt out by setting the environment variable:
export AGENTICMAIL_TELEMETRY=0
# or
export DO_NOT_TRACK=1
Telemetry is also automatically disabled in CI environments.
plugin id mismatch (manifest uses "agenticmail", entry hints "openclaw")
This is harmless. OpenClaw infers the plugin ID from the npm package name (@agenticmail/openclaw) but the manifest declares "id": "agenticmail". The plugin loads and works correctly.
If OpenClaw reports the plugin path not found, update plugins.load.paths in ~/.openclaw/openclaw.json to point to the correct location:
npm prefix -g
# Plugin is at: <prefix>/lib/node_modules/@agenticmail/openclaw
agenticmail: command not foundUse npx agenticmail for one-off usage, or install globally with npm install -g @agenticmail/cli.
MIT - Ope Olatunji (@ope-olatunji)
Real email and SMS for AI agents — send mail, receive verification codes, drive a real inbox.
{ "mcpServers": { "io.github.agenticmail-mcp": { "command": "npx", "args": [ "-y", "@agenticmail/[email protected]" ], "env": { "AGENTICMAIL_API_KEY": "<secret>", "AGENTICMAIL_MASTER_KEY": "<secret>", "AGENTICMAIL_API_URL": "<value>" } } }}工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式，而不是 PlugMCP 代理伺服器。
發布者列出了以下環境變數：AGENTICMAIL_API_KEY, AGENTICMAIL_MASTER_KEY, AGENTICMAIL_API_URL。
Agenticmail 透過 stdio 在本機執行。
上次檢查時間：2026-11-13。 Real email and SMS for AI agents — send mail, receive verification codes, drive a real inbox.
