AgenticMail
OfficialAgenticMail is an MCP/API server for giving AI agents real email/phone identities and coordinating multi-agent work.
Email operations: send, reply, forward, broadcast, list, read, search, delete, move, batch process, organize folders, manage drafts, scheduled sends, templates, signatures, contacts, tags, rules, spam, and pending-approval emails.
Multi-agent coordination: discover/create/stop/resume/delete agents, message agents asynchronously, call agents synchronously with timeouts/output schemas, check/claim/submit tasks, wait for matching email, inspect worker activity/logs, and save thread memory.
Inbox awareness: use SSE-based waits, inbox digests, message checks, read/unread state, relay search/import, and activity monitoring.
Email gateway setup: configure Gmail/Outlook relay or Cloudflare custom-domain email, manage aliases, check gateway status, send test email, search/purchase domains, and get payment/setup guidance.
SMS: configure Google Voice or 46elks, send/list SMS, extract verification codes, parse forwarded SMS, and record SMS.
Phone and voice: configure 46elks/Twilio transports, start tracked call missions with strict safety policy, inspect status/transcripts, cancel calls, handle operator queries, and inject live answers.
Telegram: configure a bot, send/list/poll Telegram messages, and use Telegram as an operator channel.
Persistent memory: set/get/search/list/delete memories, record reflections, generate memory context, and inspect memory stats.
Media tools: text-to-speech, voice listing, image editing, video editing/cinematic edits, audio editing, media metadata, video understanding, and voice cloning.
Skills: list, search, and load phone-call skill playbooks.
Admin/ops: check health, identify the current agent, update metadata, manage a SQLite/Postgres/MySQL/Turso-style storage layer, and discover/invoke additional tools.
Domain mode uses Cloudflare for automatic DNS configuration (MX, SPF, DKIM, DMARC, tunnel CNAME), Cloudflare Tunnel for secure inbound traffic, and Cloudflare Email Worker for routing. Supports domain purchase via Cloudflare Registrar.
Relay mode allows agents to send and receive internet email through a Gmail account, using a +alias address for each agent. Setup takes minutes and leverages Gmail's SMTP/IMAP for mail delivery.
Google Voice integration gives agents a real phone number for sending and receiving SMS, extracting verification codes, and handling phone calls. Includes a setup wizard to handle Gmail and Voice account matching.
The first platform to give AI agents real email addresses and phone numbers. Send and receive email, SMS, and verification codes — all programmatically.
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 bootstrapZero 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.
📄 Research Paper
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]
✨ What's new — media toolset (unreleased)
A local, opt-in media / video-editing toolset for AgenticMail agents.
Nine media tools.
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, andmedia_capabilities. Available as MCPmedia_*tools and OpenClawagenticmail_media_*tools, both thin clients of new/media/*API routes over a coreMediaManager.Cinematic video editing. Beyond trim/convert/compress: color grading presets, crossfade/wipe transitions, timed text overlays, picture-in-picture, split screen, Ken Burns, frame-interpolated slow motion, watermarks, concatenation, audio mixing, and whisper.cpp-driven auto-captions.
Gracefully degrading. The underlying binaries (ffmpeg, ffprobe, ImageMagick, whisper.cpp, Python) are not bundled — every tool feature-detects the binary it needs and returns an actionable install hint if it is missing. The server never crashes. A
mediablock on/healthand themedia_capabilitiestool surface what is available.Safe by construction. Every binary is invoked via
execFilewith 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.
✨ What's new in 0.9.54
Twilio joins 46elks as a phone transport provider.
Pick your carrier.
PhoneTransportProvideris now46elksortwilio— chosen at phone setup. 46elks behaviour is unchanged; Twilio is at full parity (outbound call-control + realtime voice).Twilio call-control. Outbound calls via the Twilio
Calls.jsonREST API, TwiML webhooks, status-callback cost tracking. Inbound webhooks are verified with theX-Twilio-Signatureheader (HMAC-SHA1, timing-safe, fail-closed) on top of the per-mission token.Twilio realtime voice. A Twilio Media Streams ↔ OpenAI Realtime bridge.
RealtimeVoiceBridgewas generalised behind aRealtimeTransportAdapterseam — 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 usesaudio/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.
✨ Earlier — 0.9.53
Realtime voice tools + a Telegram channel.
The voice agent can now use tools mid-call. The OpenAI Realtime session declares
session.tools;RealtimeVoiceBridgedispatches the model's function calls through an injectedToolExecutor, returnsfunction_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.Lookup tools.
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.Telegram channel. A user registers a Telegram bot token, links a chat, and can message their AgenticMail agent — and get replies — over Telegram. The inbound webhook authenticates with a constant-time secret-token compare; it also carries
ask_operatornotifications and approvals.Security. web_search output is fenced as untrusted before it reaches the model; operator email replies are verified against
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.
✨ Earlier — 0.9.52
Realtime voice + OpenClaw memory.
Realtime voice bridge. A phone mission can now hold a live conversation.
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 asresponse.output_audio.deltaand is relayed to 46elks, server-side VAD handles turn-taking, and caller barge-in fires a 46elksinterrupt. 46elks streams a call to the new/api/agenticmail/calls/realtimeWebSocket endpoint, which matches the connection to its mission by 46elkscallidand runs the bridge. SetOPENAI_API_KEY(env orconfig.json) to enable it.Memory in the voice session. Before the call starts, the agent's persistent memory is rendered with
generateMemoryContext()and folded into the Realtime sessioninstructions— 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.OpenClaw memory tools.
agenticmail_memory,agenticmail_memory_reflect,agenticmail_memory_context, andagenticmail_memory_statsbring the universal per-agent memory to OpenClaw agents — 69 → 73 tools.Bridge hardening. Per-frame audio size cap (an oversized frame is dropped, never forwarded), bounded pre-connect buffer, fail-closed connection auth (timing-safe token compare; no unknown-mission-vs-wrong-token oracle), and a terminal-state guard so a late event can't resurrect a finished mission.
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.
✨ Earlier — 0.9.51
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, andgenerateMemoryContext()which ranks + renders memory as a markdown block for prompt injection. Backed by a zero-dependency BM25F search index and anagent_memorytable. Ported from the AgenticMail Enterprise memory engine, org-stripped — memory is personal to each agent.Memory API —
/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.MCP tools —
memory,memory_reflect,memory_context,memory_statsso any MCP client can give its agent durable memory.Agent-deletion cleanup — deleting an agent purges its
agent_memoryrows; no orphaned memory is left behind.
✨ Earlier — 0.9.1
The visibility release — closes every "what just happened?" gap from 0.9.0.
Lone wakes fire immediately. 0.9.0's debounce window blocked even single replies for 30 s, making the dispatcher look dead. Leading-edge fire + trailing-edge coalesce now: first event for a
(agent, thread)spawns instantly; bursts within the window collapse into one trailing wake.Dispatcher process heartbeat.
check_activitynow showsdispatcher: { state: 'alive' | 'unhealthy' | 'missing', uptimeMs, channels, coalesceQueueSize, ... }. The host can finally answer "is the dispatcher up?" in one query.Skipped-wake ring buffer. Every filter decision (thread-closed, allowlist-excluded, wake-on-cc, budget-exhausted) is posted with a reason;
check_activitysurfaces the last 100. No more "did my mail land? did it skip?" guessing.Per-agent
wake_on_cc: falseflag. Coder agents can register a preference: never wake when only on Cc, regardless of sender.PATCH /accounts/:id/wake-on-cc.Display-name regex fix in
deriveDefaultWakeList. Senders using"Vesper <vesper@localhost>"form no longer fall through to "no allowlist → wake everyone".Web UI shows To / Cc / Bcc as separate labeled rows in the message view (previously lumped under one
to:line).docs/wake-patterns.mddocuments every wake shape + 5 recommended patterns.
✨ Earlier — 0.9.0
The wake-context release. Multi-agent thread cost goes from linear-in-thread-length to roughly flat.
Layered wake-context system. Every wake used to re-read the entire thread from scratch (12 messages × ~1 KB = 12 KB of token spend just to rehydrate, before any reasoning). Now the dispatcher prepends two blocks to every wake prompt: Layer 1 — ThreadCache (envelopes + previews of the last 10 messages, shared across CC'd agents) and Layer 2 — AgentMemory (a markdown file each agent writes at end-of-wake describing its own commitments and last actions). Agents read the new event + these two blocks and decide; they don't
read_emailprior history. New MCP toolssave_thread_memoryandget_thread_id.wakedefault 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 inwake. Opt back into the old behaviour withwake: 'all'.Wake coalescing. Within 30 s for the same
(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 acoalescedbatch prompt. Wake-budget charges once. Configurable viawakeCoalesceMs.
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.
✨ Earlier — 0.8.31
Compact-and-continue — workers can now run across multiple SDK turns. On a context-overflow error the dispatcher synthesises a breadcrumb checkpoint from the captured log, builds a "resuming after context reset" continuation prompt, and loops (capped at 4 iterations).
Typed task contracts —
call_agent/POST /tasks/assignaccept anoutputSchema(JSON Schema, draft-7 subset).submit_resultvalidates against it; mismatches return 400 with the validator errors so the worker can retry with a corrected shape.Delete + Move-to-Spam buttons in the message view; Compose auto-saves to Drafts every 2s.
All Mailfolder hides itself on servers that don't have one (Stalwart, most non-Gmail). Select-all checkbox now wires through.Logo background stripped — bow PNG is now RGBA with proper transparency.
✨ Earlier — 0.8.29
Star button wired — clicking the star toggles IMAP's
\Flaggedflag via the newPOST /mail/messages/:uid/starendpoint. Backed byMailReceiver.setStarredin@agenticmail/core. Optimistic UI; revert on failure.Gmail-compact list UX — single 36 px rows (was 64 px stacked), subject + preview on one truncated line separated by an em-dash, leading checkbox column, sticky list-toolbar with select-all + refresh + count. Same layout for every folder.
Compose button down to 48 px (Gmail's actual size); the giant pink pill is gone.
✨ Earlier — 0.8.27
Folder bug fix — Sent / Drafts / Spam / Trash were returning empty in the web UI because hard-coded folder names didn't match Stalwart's actual IMAP names (e.g.
Sent ItemsnotSent). Now auto-discovered per agent and matched against every common server convention (Stalwart, Gmail, Outlook, macOS Mail).Two-line preview on every list row — web UI uses
/mail/digest?folder=…everywhere instead of/mail/inbox(no preview) +/mail/folders/:folder(no preview).URL reflects current folder — hash router now uses
#/folder/<id>(sent, drafts, spam, …). Back/forward works, URLs are shareable, refresh stays put.Stop hook output rewritten — terser, audience-neutral, includes body preview. Drops the instruction-leakage from 0.8.25/26.
✨ Earlier — 0.8.25
Workers can now run for hours — dropped the 30-min hard timeout. Each worker writes a per-turn log at
~/.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 tooltail_workerto read a running worker's log live;check_activitynow shows last tool used, turn count, and astaleflag (no auto-eviction).Autonomous-mode awareness — the mail hook now registers on the Stop event too. Long headless Claude Code runs (no user prompts firing for hours) finally see teammate replies — the hook returns
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.Fixed
agenticmail-mail-hook: command not founderrors — hook is now registered with an absolute path resolved at install time. Resilient to any$PATHconfiguration; old installs auto-heal on the nextagenticmail claudecoderun.Web UI fixes —
(m.flags ?? []).includes is not a functioncrash 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.Official logos — Claude starburst (from Wikipedia) and the AgenticMail
@mark frombranding/now ship bundled and render as the host avatar + topbar / favicon.Selective wake —
wake: ["alice", "bob"]onsend_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.Thread-close markers —
[FINAL],[DONE],[CLOSED], or[WRAP]in a subject tells the dispatcher this thread is done; no more wakes on any reply.check_activityMCP 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?"Comprehensive markdown rendering in the shell's email viewer — bold, italic, headings, lists, task lists, tables, fenced code, links, images, HTML entities, depth-colored quote stripes (instead of literal
>>>>).LLM-tolerant tool inputs —
batch_mark_read({ uids: "[1,2,3]" })and other common stringification mistakes now just work; coerced before validation.Wake-budget circuit breaker — caps per-(agent, thread) wakes at 10 per 24h to stop reply loops and storms.
Dedup guidance — wake prompts now tell agents to check their prior contributions before redoing work.
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.
Table of Contents
Related MCP server: zerodrop-mcp
Why 🎀 AgenticMail?
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:
Isolated mailboxes — each agent has its own email address, inbox, and credentials. Agents can't read each other's mail.
Internet email connectivity — two gateway modes to send/receive real email (Gmail relay or custom domain with DKIM/SPF/DMARC).
Security guardrails — outbound scanning prevents agents from leaking API keys, passwords, or PII. Blocked emails require human approval.
Agent collaboration — agents can email each other, assign tasks, and make synchronous RPC calls.
SMS / Phone number access — integrate Google Voice or 46elks for SMS receive/send, verification code extraction, and phone number access for AI agents.
Realtime voice calls — bridge a phone mission to an OpenAI Realtime (
gpt-realtime) session so an agent can hold a live two-way conversation, with its persistent memory folded into the call.Persistent agent memory — every agent has a categorised, confidence-decaying, searchable long-term memory that survives across conversations and is injected into prompts and voice sessions.
Smart orchestration —
call_agentreplaces basic sub-agent spawning with auto mode detection, dynamic timeouts, runtime tool discovery, and async execution for long-running tasks.Tool integrations — 100 MCP tools for any AI client, 89 OpenClaw tools, and a 44-command interactive shell.
Self-updating —
agenticmail updatechecks npm, verifies OpenClaw compatibility, and updates both packages automatically.
Features
Email Operations
Send email with text, HTML, attachments, CC/BCC, reply-to, and custom headers
Receive email via IMAP with real-time SSE event streaming (IMAP IDLE)
Reply and forward with proper In-Reply-To and References headers for threading
Search by sender, subject, body text, date range, read/unread status
Folders — create, list, move messages between folders
Batch operations — mark read/unread, delete, move multiple messages at once
Drafts — save, edit, and send draft emails
Templates — reusable email templates with variable substitution
Scheduled sending — queue emails for future delivery
Signatures — per-agent email signatures
Tags — label and categorize messages
Contacts — manage address book per agent
Multi-Agent
Account management — create, list, delete agents with unique email addresses
Agent-to-agent email — agents can email each other directly via
@localhostTask system — assign tasks to agents, claim, submit results, track status
RPC calls — synchronous agent-to-agent calls with timeout (long-poll + SSE notification)
Agent directory — discover other agents by name
You 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.
Gateway (Internet Email)
Relay mode (beginner) — use your existing Gmail or Outlook as a relay. Emails appear as
you+agentname@gmail.com. Setup takes 2 minutes.Domain mode (advanced) — custom domain via Cloudflare. Agents send from
agent@yourdomain.comwith full DKIM signing, SPF, and DMARC records.Automatic DNS configuration (MX, SPF, DKIM TXT, DMARC, tunnel CNAME)
Cloudflare Tunnel for secure inbound traffic without exposing ports
Cloudflare Email Worker for Email Routing (catch-all → worker → AgenticMail)
Optional Gmail SMTP outbound relay for residential IPs without PTR records
Domain purchase via Cloudflare Registrar
DNS backup before any modifications
Automatic
@domainemail alias for all existing agents
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.comand 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
@localhostmail 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.comandsecretary@localhostare indistinguishable from the dispatcher's point of view.The host bridge takes a different path. Mail to
yourrelay+claudecode@gmail.comoryourrelay+codex@gmail.comdoesn't spawn a worker — it goes tohandleBridgeMail, which uses the host SDK'sresumeoption to wake your last session headlessly. If that fails (session expired, host CLI not running), it falls through to the bridge-escalation email atsetup_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.comin a leaked address book can drive worker turns at your expense. Throttles available, ordered from least invasive:Let the
wake-budgetguard indispatcher.handleEventrate-limit naturally (default cap per minute per agent).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).
For agents that should be internal-only, set
metadata.hostto a value no dispatcher matches, or stop the relay's IMAP poller from publishing on that inbox.
Security
Outbound guard — scans every outgoing email for sensitive data patterns:
API keys and tokens (AWS, OpenAI, Stripe, GitHub, etc.)
Passwords and credentials
Private keys (SSH, PGP, RSA)
PII patterns (SSN, credit card numbers)
Internal URLs and configuration data
Blocked emails are held for human-only approval (agents cannot self-approve)
Spam filter — rule-based scoring engine for inbound email:
Categories: phishing, scam, malware, commercial spam, social engineering, lottery scam
Configurable threshold (default: 40)
Skips internal agent-to-agent emails
Runs on both relay inbound and SSE event streams
Human-only approval flow — when an agent's email is blocked:
The agent is informed the email was blocked and told to notify their owner
The owner receives a notification email with full blocked email content, warnings, and pending ID
Only the master key holder can approve or reject (
POST /mail/pending/:id/approve)Agents can list and view their own pending emails but cannot approve or reject them
System prompt guidelines instruct agents to inform their owner and wait, never attempt to bypass
DKIM/SPF/DMARC — automatic DNS setup in domain mode for email authentication
Rate limiting — configurable per-endpoint rate limits
SMS / Phone Number Access
Provider selection — choose Google Voice legacy forwarding or 46elks direct SMS API/webhooks
46elks integration — send SMS through the provider API and receive inbound SMS through a secret-protected webhook
Google Voice integration — give agents a real phone number via Google Voice
Direct Voice web reading (primary, instant) — reads SMS directly from voice.google.com via browser
Email forwarding (fallback) — Google Voice forwards SMS to email, agent auto-detects and records them during relay polling
Separate Gmail polling — for users whose GV Gmail differs from relay email, runs a dedicated IMAP poll
Verification codes — automatic extraction of OTP/verification codes from SMS (4-8 digit, alphanumeric, Google G-codes)
Send SMS — direct provider API send when configured, or Google Voice web automation instructions for legacy configs
Smart setup wizard — validates Gmail/GV email matching, warns about mismatches, collects separate credentials when needed
Realtime Voice Calls
Live two-way conversation —
RealtimeVoiceBridgebridges a phone mission to an OpenAI Realtime (gpt-realtime) session so an agent can actually talk on the call, not just place itTwo carriers — 46elks or Twilio — pick the provider at phone setup;
RealtimeVoiceBridgeis generalised behind aRealtimeTransportAdapterso 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 — OpenAIaudio/pcmu, no transcoding). Server-side VAD for turn-taking, caller barge-in relayed to the carrier.Memory in the call — the agent's persistent memory is rendered and folded into the Realtime session instructions, so the model speaks with full continuity, as if it had always known those things
Mission-tracked — the bridge resolves the connection to its phone mission by 46elks
callid, authenticates the connection token, and persists the conversation transcript to the missionHardened — per-frame audio size cap, bounded pre-connect buffer, fail-closed connection auth, terminal-state guard
Opt-in — set
OPENAI_API_KEYto enable; without it, phone missions still place and track calls (call-control only)Tools on the call — the Realtime session can call functions mid-call:
ask_operator(human-in-the-loop — pause, ask the operator, resume, or call back on disconnect),web_search,recall_memory,get_datetime
Telegram Channel
Chat with your agents over Telegram — register a Telegram bot token, link a chat, and message your AgenticMail agent (and get replies) from Telegram
Inbound webhook — authenticated with a constant-time
X-Telegram-Bot-Api-Secret-Tokencompare; uniform 403 on mismatchOperator channel — carries
ask_operatornotifications and approvals, so a phone agent can reach you on Telegram mid-callSecrets protected — bot tokens encrypted at rest, redacted from every log line and error
Media Toolset
Nine local media tools —
media_tts,media_tts_voices,media_image_edit,media_video_edit,media_audio_edit,media_info,media_video_understand,media_voice_clone, plusmedia_capabilitiesText-to-speech — synthesise speech with Edge TTS (twelve voice presets); returns OGG/Opus, ready to send as a voice note
Image editing — resize, crop, rotate, convert, compress, text overlay, flip, blur, sharpen, grayscale (ImageMagick)
Video editing — basic (trim, GIF, compress, resize, add/remove audio, speed) and cinematic (color grading, transitions, captions, picture-in-picture, split screen, Ken Burns, slow motion, watermark, concatenate, auto-caption) — all via ffmpeg
Audio editing — trim, convert, merge, volume, speed, extract-from-video, reverse, fade
Video understanding — extract frames + transcribe audio (whisper.cpp) into a structured timeline an agent can read before editing
Voice cloning — reference-voice speech synthesis via F5-TTS (you supply the reference sample + transcript)
Opt-in / gracefully degrading — the underlying binaries (ffmpeg, ffprobe, ImageMagick, whisper.cpp, Python) are not bundled; every tool feature-detects the binary it needs and returns a clear, actionable install hint when one is absent — the server never crashes. Call
media_capabilities(or read the/healthmediablock) to see what is availableSafe by construction — every binary is invoked via
execFilewith 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 directory
Persistent Agent Memory
Long-term, evolving knowledge — each agent has a categorised memory (knowledge, preference, correction, skill, reflection, …) that survives across every conversation
Confidence + decay — entries carry a confidence score that decays for unaccessed knowledge;
criticalentries never decay; low-confidence and expired entries are prunedBM25F search — a zero-dependency full-text index ranks recall by relevance, importance, recency, and access count
Prompt + voice injection —
generateMemoryContext()renders a ranked markdown block for injection into agent prompts and realtime voice sessionsPrivate per agent — every memory endpoint is scoped to the authenticated agent; deleting an agent purges its memory
Everywhere —
/memory*REST endpoints, MCP tools (memory,memory_reflect,memory_context,memory_stats), and OpenClaw tools (agenticmail_memory*)
Smart Orchestration (call_agent)
Auto mode detection — reads task complexity, picks light/standard/full mode automatically
Dynamic timeouts — 60s for quick tasks, 5+ minutes for deep research, 1 hour for async
Runtime tool discovery — probes host config for available tools instead of static deny lists
Async execution — long-running tasks run independently, auto-compact context, email results when done
Structured RPC — sub-agents return JSON, not raw text
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 updateor/updatein shell, with OpenClaw compatibility check
Architecture
┌──────────────────────────────────────────────────┐
│ 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 │
└──────────────────────┘Data Flow
Sending email (relay mode):
Agent calls
POST /mail/sendwith recipient, subject, bodyAPI runs outbound guard scan — if sensitive data found, email is blocked and owner notified
GatewayManager detects external recipient → routes to RelayGateway
RelayGateway sends via Gmail SMTP as
owner+agentname@gmail.comReply-To set to agent's relay address so replies route back
Sending email (domain mode):
Agent calls
POST /mail/sendOutbound guard scan runs
GatewayManager rewrites
agent@localhost→agent@yourdomain.comEmail submitted to local Stalwart via SMTP (port 587)
Stalwart signs with DKIM, resolves MX, delivers directly (or via Gmail relay)
Receiving email (relay mode):
RelayGateway polls Gmail IMAP every 30 seconds for new messages
New email detected → parsed → spam scored
If not spam, delivered to agent's local Stalwart mailbox via SMTP
X-AgenticMail-Relay: inboundheader added for identificationInboxWatcher (IMAP IDLE) fires SSE event to connected clients
Receiving email (domain mode):
External sender sends to
agent@yourdomain.comCloudflare Email Routing catches all → routes to Email Worker
Worker reads raw RFC822 message, base64-encodes, POSTs to
/api/agenticmail/mail/inboundInbound endpoint validates secret, parses email, delivers to agent's mailbox
InboxWatcher fires SSE event
Quick Start
Prerequisites
Node.js 22 or later (we use the built-in
node:sqlitemodule — zero native compilation, nonode-gypheadaches)brew(macOS) orapt(Linux) so the wizard can install Colima / Docker if you don't already have it
Two install paths
Path | When to use | Command |
Autonomous ✨ | Letting an AI agent (e.g. Claude Code) install AgenticMail on your behalf, or you just want zero questions |
|
Interactive | You want to connect a Gmail relay or your own domain right away |
|
Autonomous install (recommended for most users)
# 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 bootstrapEither 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.Waits for
GET /api/agenticmail/healthto come up on the configured port (defaulthttp://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).
Interactive install
npm install -g @agenticmail/cli
agenticmail setupThe 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
openaiApiKeyin~/.agenticmail/config.json(file mode 0600).Phone calling — pick your carrier (
46elksortwilio), 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
@BotFatherand your chat id. The token is verified with Telegram before it's stored; the channel comes up in poll mode andagenticmail startauto-spawns a standalone bridge service that wakes the agent on inbound DMs with the full MCP toolset (memory, send_email, call_phone, …) available.
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:
# 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 stopSkip external email entirely?
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.
What the wizard does for you
Checks Node, Colima/Docker, brew/apt
Generates a master API key (saved to
~/.agenticmail/config.json, file mode 0600)Initialises the SQLite database (
node:sqlite— Node 22+ built-in, no native compilation, no prebuilt binaries needed)Starts Stalwart in a Docker container
Creates your first agent with its own email and API key
Optionally configures a gateway (relay or domain) for internet email
Optionally enables realtime voice (OpenAI API key), phone calling (46elks or Twilio), and the Telegram channel
Send your first email (programmatic)
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: 'colleague@example.com',
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);Send your first email (CLI)
agenticmail> /send
To: someone@example.com
Subject: Test email
Body: Hello from the AgenticMail shell!
Email sent! Message ID: <abc123@localhost>Send your first email (curl)
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": "someone@example.com",
"subject": "Hello",
"text": "Sent via the AgenticMail API."
}'CLI Commands
AgenticMail includes a full CLI for managing your server. All commands are available via agenticmail <command> or npx @agenticmail/cli@latest <command>.
Core Commands
Command | Description |
| Start the server (runs setup first if not initialized). Opens the interactive shell after startup. This is the default command — just run |
| ✨ Zero-question install. One-shot pipeline: setup + service install + claudecode wiring. Designed for AI agents (Claude Code, scripts, CI) to run on a user's behalf — no prompts, no decisions. Skips Gmail relay and SMS setup (which need user-owned credentials); add them later with |
| Run the setup wizard interactively. Walks you through system checks, account creation, service startup, email connection (Gmail/Outlook/custom domain), phone number (SMS) setup, realtime voice (OpenAI API key), phone calling (46elks or Twilio), the Telegram channel, and OpenClaw integration. Pass |
| Start the server and open the interactive shell. Ensures Docker is running, Stalwart is up, and the API server is reachable. Automatically installs the auto-start service if not already set up. |
| 👀 Drop into the interactive shell against an already-running server. Use this to monitor every agent's inbox, send mail on their behalf, watch the dispatcher event feed, or run any of the 44+ shell commands. Exits cleanly with |
| 🌐 Open the Gmail-style web UI in your browser. Two-column layout (sidebar with Compose + folders / content pane), 24×24 vector icons, hash router, real-time SSE updates, full markdown rendering, compose + reply with the |
| Stop the server. Kills the background API server process. If auto-start is enabled, it will restart on next boot. Use |
| Show what's running. Displays the status of Docker, Stalwart, the API server, email connection, and auto-start service. |
Integration Commands
Command | Description |
| Set up AgenticMail for OpenClaw. Starts infrastructure, creates an agent, configures the OpenClaw plugin, enables agent auto-spawn via hooks, and restarts the OpenClaw gateway. |
| ✨ Set up AgenticMail for Claude Code. Provisions a dedicated "claudecode" bridge agent, writes an MCP server entry to |
Service Management (Auto-Start)
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.
Command | Description |
| Show auto-start status. Displays whether the service is installed and running. |
| Install the auto-start service. AgenticMail will start automatically on boot. The startup script waits up to 10 minutes for Docker to be ready, then checks that Stalwart is running (starts it if needed), then launches the API server. |
| Remove the auto-start service. AgenticMail will no longer start on boot. |
| Reinstall the service. Use this after config changes or updates to refresh the service file. |
What happens on reboot:
Your computer starts → Docker Desktop launches (its own auto-start)
Stalwart mail server starts (
restart: unless-stoppedin Docker)AgenticMail startup script waits for Docker to be ready (up to 10 min)
Script verifies Stalwart is running (auto-starts it if Docker restarted without it)
API server starts and begins accepting requests
If the API server crashes, the system service automatically restarts it.
Maintenance Commands
Command | Description |
| Update to the latest version. Checks npm for a new version, updates the CLI and OpenClaw plugin, and restarts the OpenClaw gateway if applicable. |
| Show available commands. |
Logs
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)
Gateway Modes
AgenticMail supports two modes for sending/receiving real internet email:
Relay Mode (Beginner-Friendly)
Use your existing Gmail or Outlook account as a relay. No domain purchase needed. Setup takes under 2 minutes.
How it works:
Outbound: emails sent via your Gmail/Outlook SMTP as
you+agentname@gmail.comInbound: AgenticMail polls your Gmail/Outlook IMAP for new messages addressed to
you+agentname@gmail.comand delivers them to the agent's local mailboxGmail's
+sub-addressing routes replies back to the right agent
Setup:
# 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": "you@gmail.com",
"password": "xxxx xxxx xxxx xxxx"
}'Requirements:
Gmail: App password (not your regular password)
Outlook: App password from Microsoft account security settings
Domain Mode (Advanced)
Full custom domain with Cloudflare. Agents send from agent@yourdomain.com with proper email authentication.
What gets configured automatically:
Cloudflare DNS zone creation
MX records pointing to Cloudflare Email Routing
SPF record (
v=spf1 include:_spf.mx.cloudflare.net ~all)DKIM key generation and TXT record
DMARC record (
v=DMARC1; p=quarantine)Cloudflare Tunnel (CNAME record, ingress rules)
Cloudflare Email Worker deployment (catches all inbound email)
Catch-all Email Routing rule → Worker → AgenticMail inbound endpoint
Stalwart hostname, DKIM signing, domain principal
@domainemail aliases for all existing agentsOptional: Gmail SMTP outbound relay, domain purchase
Setup:
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": "you@gmail.com",
"appPassword": "xxxx xxxx xxxx xxxx"
}
}'Cloudflare API token permissions needed:
Zone: DNS (Edit), Email Routing (Edit)
Account: Cloudflare Tunnel (Edit), Workers Scripts (Edit), Registrar (Edit — only if purchasing domains)
Packages
This is a TypeScript monorepo. Seven packages, each shipped to npm independently.
Package | Description | Install |
CLI, setup wizard, interactive shell. Install this to get started. |
| |
Core SDK — accounts, SMTP/IMAP, gateway, spam filter, outbound guard, storage |
| |
Express REST API server with 75+ endpoints |
| |
MCP server with 100 tools for any MCP-compatible AI client |
| |
Anthropic Claude Code integration — registers MCP server + native subagents + lifecycle hooks + dispatcher daemon |
| |
OpenAI Codex CLI integration — same architecture as |
| |
OpenClaw plugin with 89 tools and skill definition |
|
Plugin folders (host marketplace manifests, separate from npm packages):
Folder | Host | What's inside |
Claude Code |
| |
OpenAI Codex CLI |
|
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)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
Method | Path | Auth | Description |
|
| Agent | Send email (text, HTML, attachments) |
|
| Agent | List inbox messages (paginated) |
|
| Agent | Inbox with body previews |
|
| Agent | Read full email with headers and attachments |
|
| Agent | Search by from, subject, body, date |
|
| Agent | Move to folder |
|
| Agent | Report as spam |
|
| Agent | List all folders |
|
| Both | List blocked outbound emails |
|
| Master | Approve blocked email |
|
| Master | Reject blocked email |
Accounts | |||
|
| Master | Create new agent |
|
| Master | List all agents with metadata |
|
| Agent | Get own agent info |
|
| Master | Delete agent (with email archival) |
|
| Both | Agent discovery directory |
Events | |||
|
| Agent | SSE stream — new email with route metadata, flags, expunge events |
Gateway | |||
|
| Both | Current gateway mode and health |
|
| Master | Configure relay mode |
|
| Master | Configure domain mode |
|
| Both | Send a test email |
Tasks | |||
|
| Both | Assign task to another agent |
|
| Both | Synchronous agent-to-agent RPC (long-poll) |
|
| Agent | List tasks assigned to me |
|
| Agent | Claim a pending task |
|
| Agent | Submit task result |
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.
MCP Integration
The MCP server exposes 80+ tools to any MCP-compatible AI client via stdio transport.
Setup
Add to your MCP client configuration (e.g., .mcp.json or project settings):
{
"mcpServers": {
"agenticmail": {
"command": "npx",
"args": ["-y", "@agenticmail/mcp"],
"env": {
"AGENTICMAIL_API_URL": "http://127.0.0.1:3829",
"AGENTICMAIL_API_KEY": "ak_your_agent_key"
}
}
}
}Desktop Clients
For desktop AI applications, add the same configuration to your app's MCP config file (check your app's documentation for the file location).
What your AI can do
Once connected, your AI can:
"Check my inbox" →
list_inbox"Send an email to john@example.com about the project update" →
send_email"Reply to that last email saying thanks" →
reply_email"Search for emails from Sarah about the budget" →
search_emails"Create a draft response to the client" →
manage_drafts"What tasks are assigned to me?" →
check_tasks"Ask the research agent to look up competitor pricing" →
call_agent
See the MCP package README for the full tool list.
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:
Registers the AgenticMail MCP server in the host's config so the model can see all 100 tools.
Surfaces every AgenticMail account as a native sub-agent the model can dispatch to.
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.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.
Currently shipping
Host | Package | Plugin folder | Status |
Anthropic Claude Code | Shipping (0.2.x) | ||
OpenAI Codex CLI | Shipping (0.1.x) |
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).
Picking the right install path
You want… | Run |
One-line setup for Claude Code |
|
One-line setup for Codex |
|
Install both side-by-side | Run both — they don't conflict. Each writes to its own host's config; the AgenticMail accounts are shared. |
Marketplace install (Anthropic plugin store) | Drop |
Marketplace install (Codex | Copy |
Programmatic (your own provisioning script) |
|
Cross-host coordination
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.
Roadmap
Host | Status | Notes |
xAI Grok Build CLI | Researched — see wiki | Blocked on getting a SuperGrok Heavy seat to validate the closed-beta config-file paths against the community CLI proxy. ~80% architectural overlap. |
Nous Research Hermes Agent | Researched — see wiki | Python-native plugin ( |
OpenClaw Integration
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 openclawThat'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.
Manual Configuration
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.
Chat with Your AI Agent
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. │
╰──────────────────────────────────────╯WebSocket connection to OpenClaw gateway with Ed25519 device auth
Bubble-style chat UI with markdown rendering
Animated thinking indicator with elapsed timer
Multi-line input (Enter sends,
\+ Enter for new lines)
Smart Sub-Agent Spawning
The call_agent tool intelligently spawns sub-agents:
Auto mode detection — light (simple tasks), standard (web research), full (multi-agent coordination)
Dynamic timeouts — 60s / 180s / 300s based on complexity
Dynamic tool discovery — probes OpenClaw config at runtime instead of static deny lists
Async mode —
call_agent(async=true)for long-running tasks. The caller polls/tasks/assignedfor 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/inboxif you don't see an SMTP delivery.Web search fallback — uses DuckDuckGo when Brave API isn't configured
See the OpenClaw package README for the full tool list.
Interactive Shell
The CLI includes a full-featured interactive shell with 44 commands:
agenticmail> /inbox
★ 1 john@example.com Project Update 2m ago
2 sarah@example.com Re: Budget Review 1h ago
3 notifications@github.com [repo] New issue #42 3h ago
─────────────────────────────────────────────────
Page 1/3 ─ [←] prev [→] next [v] toggle previews [Esc] back
Use ↑↓ arrow keys to select, Enter to read inlineKey features:
Arrow key navigation with cursor selection
Body preview toggle (press
v)Inline email reading (press
Enter)Unread markers (
★)3-retry input validation on all prompts
Paginated views with
←/→navigation
Command Reference
Email: /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 /exitSecurity
Outbound Guard
Every outgoing email is scanned before sending. The guard detects:
Category | Examples |
API keys |
|
Credentials |
|
Private keys |
|
PII | Social security numbers, credit card patterns |
Internal data | Localhost URLs, internal IPs, config file contents |
When sensitive data is detected:
Email is blocked and saved to the
pending_outboundtableAgent receives a response explaining what was blocked and why, with instructions to inform their owner
Owner (master key holder) is notified via email with the full blocked email content, security warnings, recipient, subject, and pending ID
Owner approves or rejects via the master key API (
POST /mail/pending/:id/approveor/reject) or by replying to the notification emailAgents cannot approve or reject their own blocked emails — the approve/reject endpoints require the master key
Agents can only list and view their pending emails to check approval status
MCP and OpenClaw tools enforce this by rejecting approve/reject actions with a message directing agents to inform their owner
System prompt guidelines (OpenClaw) instruct agents to never attempt self-approval or rewrite emails to bypass detection
Spam Filter
Inbound emails are scored against rule-based patterns:
Category | Score Range | Examples |
Phishing | 10-30 | Fake login pages, urgency language, spoofed senders |
Scam | 15-25 | Nigerian prince, lottery winner, inheritance schemes |
Malware | 20-30 | Suspicious attachments, executable links |
Commercial | 5-15 | Unsolicited marketing, unsubscribe-heavy emails |
Social engineering | 10-20 | Impersonation, authority pressure |
Emails scoring >= 40 (configurable) are moved to Spam folder
Emails scoring 20-39 get a warning flag
Internal agent-to-agent emails skip spam filtering entirely
Relay-rewritten emails (
@localhostfrom, external replyTo) are always treated as external
Authentication
Master key — full admin access, required for agent creation/deletion, gateway config, email approval
Agent API keys — scoped per-agent, can only access own inbox and send from own address
Inbound webhook secret — authenticates Cloudflare Email Worker requests to the inbound endpoint
Configuration
Environment Variables
# === 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
RELAY_EMAIL=you@gmail.com # 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) ===
GMAIL_RELAY_EMAIL=you@gmail.com # Gmail address for outbound relay
GMAIL_RELAY_APP_PASSWORD=xxxx xxxx xxxx # Gmail app password
# === Debug ===
# AGENTICMAIL_DEBUG=1 # Enable verbose per-message loggingDocker Compose
# 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-stoppedSQLite Database
AgenticMail stores all state in a SQLite database at ~/.agenticmail/agenticmail.db. As of @agenticmail/core@0.7.x 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,tags
Development
Setup
git clone https://github.com/agenticmail/agenticmail.git
cd agenticmail
npm install
docker compose up -d
npm run build
npm testProject Structure
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 rootBuild Commands
# 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 runPublish to npm
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 publishAll scoped packages have "publishConfig": { "access": "public" } configured.
See CONTRIBUTING.md for development guidelines.
Telemetry
AgenticMail collects anonymous usage statistics to help improve the product. We track:
Tool call counts (which tools are popular)
Package version and OS platform
Anonymous install ID (random UUID, no personal data)
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=1Telemetry is also automatically disabled in CI environments.
Troubleshooting
OpenClaw plugin ID mismatch warning
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.
OpenClaw plugin path not found
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/openclawagenticmail: command not found
Use npx agenticmail for one-off usage, or install globally with npm install -g @agenticmail/cli.
Contributors
Thank you to everyone who has made AgenticMail better.
Code
@ope-olatunji: creator and maintainer
Armand (orbitalreach.space)
Security researchers
These people reported vulnerabilities privately so they could be fixed before disclosure. See the security advisories.
@benediktkraus: GHSA-wjjv-3mj2-39hf
@SecurePatchOps: GHSA-63gr-g7jc-v8rg
@YHalo-wyh: GHSA-hjwc-26pj-v3pm
@matte1782: GHSA-fq4x-789w-jg5h
@manus-pi and @manus-use: GHSA-h3h3-4g48-gxq9, GHSA-cpgx-gj4r-pf3w, GHSA-4x3j-9wxx-863h
@avishaigonen-pluto and @yotampe-pluto: GHSA-fgq6-mm4x-93qq, GHSA-vm2m-87j8-8w9m
@adelzaitri: GHSA-vj36-c6cj-8qmh
@EQSTLab: GHSA-m52q-h5cf-mj6c
@arpitjain099: GHSA-3jw6-982f-pp9w
@mappygrid: GHSA-p76v-w436-9wjh
@presendapp: GHSA-3gff-66q4-7m3q
@wlassalle724: GHSA-7mcc-72p6-m7p4
License
MIT - Ope Olatunji (@ope-olatunji)
Available Tools
101 toolsbatch_deleteC
Delete multiple emails by UIDs
Inputs: uids (required), folder, _account.
batch_mark_readC
Mark multiple emails as read
Inputs: uids (required), folder, _account.
batch_mark_unreadC
Mark multiple emails as unread
Inputs: uids (required), folder, _account.
batch_moveC
Move multiple emails to another folder
Inputs: to (required), uids (required), from, _account.
batch_readB
Read multiple emails at once by UIDs. Returns full parsed content for each message in a single call.
Inputs: uids (required), folder, _account.
broadcast_emailA
Send the SAME email to N agents as N SEPARATE, ISOLATED emails — no CC, no shared thread. Each recipient sees ONLY their own address on the To: line and reads the message as a private 1:1 from you. Use this when you need to fan-out an announcement, hand the same task to several workers in parallel, or poll multiple agents for independent answers without letting them see each other's replies. Not a replacement for send_email + CC — use CC when the team should see each other and collaborate in one thread; use broadcast_email when the conversations are independent. Each per-recipient email gets its own Message-ID and thread, so replies come back to you privately (and wait_for_email can filter on from: to demultiplex). WAKE SEMANTICS: by default every local @localhost recipient gets a wake (since each is the sole To: of its own delivery). Pass wake: [] to fan-out silently (no wakes), or wake: ["alice","bob"] to wake only specific recipients while still delivering to all. Outbound guard scans every per-recipient send individually; if ANY send is blocked, the response reports per-recipient status so you know what got through.
Inputs: to (required), subject (required), html, text, +3 more.
call_agentA
Synchronous RPC to delegate work to another AgenticMail agent. Pipeline: the task is queued in AgenticMail, the target agent processes it AS THEMSELVES (under their real identity, mailbox, persona, and audit trail), and the structured result returns into your call. THIS IS HOW MULTI-AGENT COORDINATION IS SUPPOSED TO WORK from any MCP host. Do not, instead, spawn one of your host's native sub-agents and tell it to "act as " — that produces output under your identity, never touches the target's inbox, and skips their persona. Pass outputSchema to require a structured deliverable shape: the API validates the worker's submit_result against the schema and rejects mismatches with validator errors, so the worker can retry with a correct shape rather than returning free-form prose. Times out after the specified duration (default 180s, max 300s).
Inputs: task (required), target (required), payload, timeout, +2 more.
call_answer_queryA
Inject an answer to a pending ask_operator query on a live phone call. The voice agent's next poll picks it up within ~3 seconds and relays the answer verbatim to the other party on the line. Use when the operator has provided info the call needs (DOB / account # / address / yes-or-no decision) — this beats redialing by a factor of 30× in wall-clock time and preserves the original call's context. If the mission was already terminated and the query auto-closed, this returns alreadyAnswered=true and is a no-op. When the call had already dropped, the answer arms a callback-on-disconnect that the scheduler dials a few seconds later with the answer baked into the continuation task.
Inputs: answer (required), query_id (required), mission_id (required), _account.
call_cancelA
Cancel a tracked phone mission in AgenticMail. Provider-side hangup is not guaranteed in this call-control slice.
Inputs: id (required), _account.
call_open_queriesA
List PENDING ask_operator queries on a phone mission (or all of an agent's missions when id is omitted). Use this BEFORE assuming a verification-style message from the operator is a fresh chat question — if there's an open query, the operator is most likely answering it. Pair with call_answer_query to inject the answer.
Inputs: id, _account.
call_phoneA
Start a tracked outbound phone mission. This is call-control only unless the configured transport reports realtime_media; risky decisions must be encoded in policy and may require the operator.
POLICY SCHEMA — every field below is REQUIRED and the literal values shown are the ONLY accepted values (anything else returns unsafe-confirm-policy / invalid-policy). Do not guess synonyms ("abort", "never_ever", true) — use the literals exactly.
Minimal valid policy (copy-paste, then adjust the cost / duration / regions to taste): { "policyVersion": 1, "regionAllowlist": ["WORLD"], "maxCallDurationSeconds": 600, "maxCostPerMission": 2.0, "maxAttempts": 1, "transcriptEnabled": true, "recordingEnabled": false, "confirmPolicy": { "paymentDetails": "never", "contractCommitment": "never", "costOverLimit": "needs_operator", "sensitivePersonalData": "needs_operator", "unclearAlternative": "needs_operator" }, "alternativePolicy": { "maxTimeShiftMinutes": 30 } }
Field requirements (the validator is strict — use these EXACT names and types):
policyVersion: the literal number 1 (NOT a string like "2025-01"). Required.
maxCallDurationSeconds: positive integer (NOT "maxDurationSeconds"). Server caps it.
maxCostPerMission: non-negative number, plain decimal (NOT "USD:2.00", NOT "maxCostUsd"). Server caps it.
maxAttempts: positive integer. Server caps it.
transcriptEnabled / recordingEnabled: boolean.
confirmPolicy field values are FIXED enums:
paymentDetails / contractCommitment: always "never" (the agent must never agree to pay or commit; recovering from a mistake costs the operator real money).
costOverLimit / sensitivePersonalData / unclearAlternative: always "needs_operator" (route the decision back through ask_operator). regionAllowlist values: "AT" | "DE" | "EU" | "WORLD". Use "WORLD" for any US/global destination; the transport's supportedRegions must intersect this set or the call is blocked as transport-region-unsupported.
Inputs: to (required), task (required), policy (required), dryRun, +2 more.
call_statusB
Get one phone mission by id, or list recent phone missions when id is omitted.
Inputs: id, limit, offset, status, +1 more.
call_transcriptC
Read the transcript entries recorded for a phone mission.
Inputs: id (required), _account.
check_activityA
Check which agents are currently being woken by the dispatcher. Use this when you sent mail to a teammate and want to know if they have actually started working, or to audit the live multi-agent state. Returns active workers with the agent name, what triggered the wake (mail UID + subject, or task id), how long they have been running, the most recent tool they invoked, how many tool calls they have made, a stale flag (true if the dispatcher has not heartbeated in 90s+), and a preview of recently-finished work. Workers may run for hours — there is no auto-eviction; staleness is just a hint. Requires master key.
Inputs: agent, _account, includeRecent.
check_gateway_statusA
Check the current email gateway status — relay mode, domain mode, or not configured
Inputs: _account.
check_healthC
Check 🎀 AgenticMail server health status
Inputs: _account.
check_messagesB
Check for new unread messages from other agents or external senders. Returns a summary of pending communications. Use this to stay aware of requests and coordinate with other agents.
Inputs: _account.
check_tasksB
Check for pending tasks assigned to you (or a specific agent) or tasks you assigned to others
Inputs: _account, assignee, direction.
claim_taskC
Claim a pending task assigned to you
Inputs: id (required), _account.
cleanup_agentsB
List or remove inactive non-persistent agent accounts (requires master API key)
Inputs: action (required), hours, dryRun, agentId, +2 more.
create_accountA
Create a new AgenticMail agent (email account + identity + API key + persona derived from role/metadata). Requires master API key. After creation: address them at <name>@localhost, delegate work via call_agent({ target: "<name>", task: ... }), or hand off via send_email / message_agent. The new agent acts as themselves — you never need to (and must not) roleplay them inside your host's native sub-agent tool.
Inputs: name (required), role, domain, _account.
create_folderC
Create a new mail folder for organizing emails
Inputs: name (required), _account.
delete_agentA
Delete an agent account. Archives all emails and generates a deletion report before removing the account permanently. Returns the deletion summary. Requires master API key.
Inputs: name (required), reason, _account.
delete_emailB
Delete an email by its UID
Inputs: uid (required), _account.
deletion_reportsA
List past agent deletion reports or retrieve a specific report by ID. Shows archived email summaries from deleted agents. Requires master API key.
Inputs: id, _account.
forward_emailA
Forward an email to another recipient. Outbound guard applies — HIGH severity content is held for review. Pass wake to limit which local recipients get a host turn from the dispatcher when this forward lands.
Inputs: to (required), uid (required), text, wake, +1 more.
get_thread_idA
Resolve the stable thread id for a message UID. Use this BEFORE calling save_thread_memory or when you want to inspect the cache for a thread. Pass the UID of any message on the thread (root or reply) — the API normalises the subject, resolves the canonical root sender, and returns the same id every time. folder defaults to INBOX.
Inputs: uid (required), folder, _account.
import_relay_emailA
Import an email from the connected Gmail/Outlook account into the agent's local inbox. This downloads the full message with all headers (Message-ID, In-Reply-To, References) so you can continue the thread using reply_email. Use search_emails with searchRelay=true first to find the relay UID.
Inputs: uid (required), _account.
inbox_digestA
Get a compact inbox digest with subject, sender, date, flags and text preview for each message. More efficient than listing then reading individually.
Inputs: limit, folder, offset, _account, +1 more.
invokeA
Call ANY AgenticMail tool by name with structured args — including tools not in your pre-loaded tool list. Use after request_tools to discover the right tool. Pass _account either at the top level OR inside args; either works. Example: invoke({ tool: "manage_signatures", args: { action: "create", name: "default", body: "—\nFola" }, _account: "Fola" }).
Inputs: tool (required), args, _account.
list_agentsA
List all AI agents in the system with their email addresses and roles. Use this to discover which agents you can call via call_agent (sync RPC) or email via send_email / message_agent (async). DO NOT spawn one of your host's native sub-agents and roleplay AS these agents — each one is a real identity with its own mailbox; just address them through AgenticMail and let them work as themselves.
Inputs: _account.
list_folderB
List messages in a specific folder
Inputs: folder (required), limit, offset, _account.
list_foldersC
List all mail folders/mailboxes
Inputs: _account.
list_inboxB
List recent emails in the agent's inbox
Inputs: limit, offset, _account.
manage_contactsC
List, add, or delete contacts
Inputs: action (required), id, name, email, +1 more.
manage_draftsC
List, create, update, send, or delete drafts. On send, you can pass wake to limit which local recipients get a host turn — same semantics as send_email.
Inputs: action (required), id, to, text, +3 more.
manage_pending_emailsA
Check the status of pending outbound emails blocked by the outbound guard. You can list all your pending emails or get details of a specific one. You CANNOT approve or reject — only the owner can do that.
Inputs: action (required), id, _account.
manage_rulesC
Manage server-side email rules that auto-process incoming messages (move, tag, mark read, delete).
Inputs: action (required), id, name, actions, +3 more.
manage_scheduledA
Manage scheduled emails: create a new scheduled email, list pending ones, or cancel one. Accepts flexible time formats for create: ISO 8601, relative ("in 30 minutes"), named ("tomorrow 8am"), day-based ("next monday 9am"), or human-friendly ("02-14-2026 3:30 PM EST").
Inputs: action (required), id, to, text, +3 more.
manage_signaturesB
List, create, or delete email signatures
Inputs: action (required), id, name, text, +2 more.
manage_spamB
Manage spam: list spam folder, report a message as spam, mark as not-spam, or get the spam score of a message. Emails are auto-scored on arrival; high-scoring messages are moved to Spam automatically.
Inputs: action (required), uid, limit, folder, +2 more.
manage_tagsB
Create, list, delete tags, tag/untag messages, get messages by tag, or get all tags for a specific message.
Inputs: action (required), id, uid, name, +3 more.
manage_templatesC
List, create, or delete email templates
Inputs: action (required), id, name, text, +2 more.
mark_readC
Mark an email as read
Inputs: uid (required), _account.
mark_unreadC
Mark an email as unread
Inputs: uid (required), _account.
media_audio_editC
Edit audio: trim, convert format, merge files, adjust volume, change speed, extract from video, reverse, fade in/out. Requires ffmpeg.
Inputs: action (required), end, files, input, +8 more.
media_capabilitiesA
Report which media binaries (ffmpeg, ffprobe, ImageMagick, whisper.cpp, Python, edge-tts) are installed and available. Media tools are opt-in — call this first to see what operations are possible before attempting them.
Inputs: refresh, _account.
media_image_editA
Edit an image: resize, crop, rotate, convert format, compress, overlay text, flip, blur, sharpen, grayscale. Requires ImageMagick.
Inputs: input (required), action (required), text, angle, +12 more.
media_infoA
Get metadata about any media file: duration, resolution, codec, bitrate, channels, etc. Requires ffprobe.
Inputs: input (required), _account.
media_ttsA
Convert text to speech using Edge TTS (free, local — requires the optional node-edge-tts package). Returns an audio file path (OGG/Opus when ffmpeg is available, else MP3).
Inputs: text (required), rate, pitch, voice, +1 more.
media_tts_voicesB
List the available text-to-speech voice presets.
Inputs: _account.
media_video_editA
Edit a video. Basic: trim, extract_frame, extract_frames, convert, gif, compress, resize, add_audio, remove_audio, speed. Cinematic: color_grade, transition, text_overlay, picture_in_picture, split_screen, ken_burns, slow_motion, watermark, concatenate, audio_mix, auto_caption. Requires ffmpeg (ImageMagick for text/captions, whisper.cpp for auto_caption).
Inputs: action (required), crf, end, fps, +39 more.
media_video_understandA
Analyse a video before editing it. Extracts frames at intervals and (when a whisper model is supplied) transcribes the audio, returning a structured timeline of what is shown and said. Requires ffmpeg; transcription additionally needs whisper.cpp + a model file.
Inputs: input (required), _account, maxFrames, whisperModel, +1 more.
media_voice_cloneA
Synthesise speech in a reference voice using F5-TTS. Requires a Python interpreter with the f5-tts and soundfile packages. You MUST supply a reference audio sample and its transcript — there is no built-in voice.
Inputs: text (required), refText (required), refAudio (required), device, +1 more.
memoryA
Your persistent, long-term memory — knowledge that survives across every conversation, like a human employee learning on the job. Use set to remember something durable (a preference, a fact, a correction, a learned skill); search to recall by topic; list to browse; get to read one entry; delete to forget. Memory is private to you and persists forever unless it decays from disuse or you delete it. Store things you would want to still know weeks from now — not transient task state.
Inputs: action (required), id, tags, limit, +6 more.
memory_contextA
Get a ranked markdown digest of your most relevant persistent memory — what you would want loaded into your working context right now. Optionally pass a query to bias the digest toward a topic. This is the same memory block a voice/phone session injects so you act with full continuity.
Inputs: query, _account, maxTokens.
memory_reflectA
Record a self-reflection into your persistent memory — an insight or lesson you want to carry forward (stored as a high-confidence reflection entry). Use this at the end of a task or conversation to capture what you learned.
Inputs: content (required), title, _account, importance.
memory_statsB
Get aggregate statistics about your persistent memory — total entries, breakdown by category / importance / source, and average confidence.
Inputs: _account.
message_agentA
Async fire-and-forget: deliver a message to another AI agent's inbox. They will process it on their own schedule (immediately if a dispatcher is attached, later otherwise) and may reply by email. Use this for non-blocking handoffs. Prefer call_agent when you need a structured reply back. Both flows let the target agent do the work AS THEMSELVES — never roleplay them inside your own host.
Inputs: text (required), agent (required), subject (required), _account, +1 more.
move_emailB
Move an email to another folder (e.g., Trash, Archive)
Inputs: to (required), uid (required), from, _account.
phone_capabilitiesB
Show the configured phone provider, caller number, supported regions, and whether realtime media is available.
Inputs: _account.
phone_transport_setupA
Configure the phone call-control transport for this agent. This stores provider credentials and webhook settings; it does not start a call. Pick ONE provider — 46elks or twilio — and supply that provider's credentials. For 46elks pass username + password; for twilio pass accountSid + authToken (or the generic username + password — for twilio username is the account SID and password is the auth token).
Inputs: phoneNumber (required), webhookSecret (required), webhookBaseUrl (required), apiUrl, +8 more.
purchase_domainA
Search for available domains via Cloudflare Registrar (requires master API key). NOTE: Cloudflare API only supports READ access — domains must be purchased manually at https://dash.cloudflare.com or from another registrar (then point nameservers to Cloudflare).
Inputs: keywords (required), tld, _account.
read_emailB
Read the full content of a specific email by its UID
Inputs: uid (required), _account.
reply_emailA
Reply to an email. Fetches the original message, auto-fills To, Subject (Re:), In-Reply-To, and References, then sends with quoted body. For multi-agent thread coordination, pass replyAll: true — the original sender lands on To:, every other thread participant lands on Cc:. Wake routing is body-aware: if your reply addresses a specific CC'd agent ("Marlow —", "@kepler", "handing off to rivet", etc.), the dispatcher wakes them automatically. If your body has no such addressing, the original sender (on To:) wakes by default. Pass wake to override explicitly (e.g. wake: ["marlow"] to force-target one agent, or wake: [] to deliver silently). Outbound guard applies — HIGH severity content is held for review.
Inputs: uid (required), text (required), html, wake, +2 more.
request_toolsA
Discover AgenticMail tools that are NOT already in your loaded tool list. Returns a text catalogue grouped by set (mail_extras, sms, agent_coord, …) with each tool name and its schema summary. After calling this, use invoke to call any tool by name. Optional filters: query (substring match on tool name/description) or sets (return only the named sets).
Inputs: sets, query, _account.
resume_agentA
Reverse a previous stop_agent call. Clears the stopped flag so the dispatcher resumes waking this agent on incoming mail and task events. The agent's inbox is exactly as it was during the pause — any mail that arrived while stopped is still there and will be picked up on the next natural wake. Requires master API key.
Inputs: name (required), _account.
save_thread_memoryA
Persist a one-paragraph memory of where THIS agent stands on the given thread. Called at the end of every wake — Claude Code reads it back into the next wake's prompt so the agent doesn't re-derive context from scratch by re-reading 10 prior messages. Pass threadId from get_thread_id. Fields are a snapshot: summary (where the thread stands), commitments (what you committed to), openQuestions (what you are blocked on), lastAction (what you just did), lastUid (newest UID you have digested). The file overwrites; you do not need to merge with the previous version — the dispatcher reads only the most recent write.
Inputs: threadId (required), lastUid, summary, _account, +3 more.
search_emailsA
Search emails by criteria (from, to, subject, text, date range). By default searches the local inbox only. Set searchRelay=true to also search the connected Gmail/Outlook account — results include relay UIDs that can be imported with import_relay_email.
Inputs: to, from, seen, text, +5 more.
send_emailA
Send an email from the agent's mailbox. The PRIMARY primitive for multi-agent coordination. Use to and cc as the email standard intends — to is the actor(s) the message is addressed to (one or two recipients in most cases); cc is everyone else on the thread for awareness. Lumping every participant on to is wrong and defeats the wake gating. WAKE SEMANTICS (0.9.0+): by default only local @localhost recipients on to: get a host wake; CC'd local agents receive the mail but don't wake — they see it on their next natural wake. To override: pass wake: ["alice","bob"] for specific agents regardless of To/CC, or wake: "all" for the pre-0.9.0 "wake every recipient" behaviour, or wake: [] to deliver silently. External emails are scanned for sensitive content; HIGH severity detections are BLOCKED for owner approval.
Inputs: to (required), subject (required), cc, html, +6 more.
send_test_emailA
Send a test email through the gateway to verify configuration (requires master API key)
Inputs: to (required), _account.
setup_email_domainA
Set up a custom domain for real internet email via Cloudflare (requires master API key). ADVANCED: Requires Cloudflare account, API token, and a domain. Emails send from agent@yourdomain.com with full DKIM/SPF/DMARC. Optionally configures Gmail SMTP as outbound relay (recommended for residential IPs). After setup with gmailRelay, use setup_gmail_alias for each agent.
Inputs: cloudflareToken (required), cloudflareAccountId (required), domain, _account, +2 more.
setup_email_relayA
Configure Gmail/Outlook relay for sending real internet email (requires master API key). BEGINNER-FRIENDLY: Just needs a Gmail/Outlook email + app password. Agents send as user+agentname@gmail.com. Automatically creates a default agent (secretary) unless skipped. Best for: quick setup, personal use, no domain needed.
Inputs: email (required), password (required), provider (required), _account, +7 more.
setup_gmail_aliasA
Get step-by-step instructions (with exact field values) to add an agent email as a Gmail "Send mail as" alias. Returns the Gmail settings URL and all field values. Required after domain mode setup with gmailRelay to show correct From address. The agent can automate this via browser tools or present instructions to the user.
Inputs: agentEmail (required), _account, agentDisplayName.
setup_guideA
Get a comparison of email setup modes (Relay vs Domain) AND the optional channels — realtime voice (OPENAI_API_KEY), phone call-control with a 46elks-vs-Twilio provider choice, and the Telegram channel — each with difficulty levels, requirements, pros/cons, and step-by-step instructions. Show this to users who want to set up real internet email, voice calls, phone, or Telegram.
Inputs: _account.
setup_operator_emailA
Save the operator's notification email address for bridge-escalation alerts. When sub-agents mail a host bridge (e.g. wake: ["codex"]) AND no fresh host session is available for a headless resume, the dispatcher forwards a digest to this address so the operator gets a phone push (via Gmail / Apple Mail / whichever app handles their address). Master-key scoped. The host agent should call this during bootstrap after asking the operator: "what email should we alert you at when sub-agents need your attention?" — the answer is typically the operator's personal Gmail with mobile push enabled. Idempotent: re-running with a new address updates the config.
Inputs: email (required), _account.
setup_paymentA
Get instructions for adding a payment method to Cloudflare (required before purchasing domains). Returns Option A (self-service link) and Option B (browser automation steps). Card details go directly to Cloudflare — never stored by 🎀 AgenticMail.
Inputs: _account.
skill_listA
List available phone-call skill playbooks, optionally filtered by category (e.g. "negotiation", "reservations", "debt-collection") or tag. Returns summaries (id, name, description, tags) — call skill_load with the id to get the full playbook.
Inputs: tag, _account, category.
skill_loadA
Load the FULL skill playbook by id. Returns the complete JSON document: principles, scripted phrases, tactic priority list, boundaries, success/failure signals, exit strategy. Use the response to ground your next turns on the call — the playbook should drive your phrasing, tactic order, and exit decisions.
Inputs: id (required), _account.
skill_searchA
Fuzzy-search skills by free-text query against name, description, tags, principles, phrases, and tactic scripts. Use this DURING a call when you need a playbook for the situation you just hit ("the rep is asking for a settlement number — what do I do?"). Returns ranked summaries; load the top match with skill_load.
Inputs: query (required), limit, _account.
sms_check_codeA
Check for recent verification/OTP codes received via SMS. Scans inbound SMS for common code patterns (6-digit, 4-digit, alphanumeric). Use this after requesting a verification code during sign-up flows.
Inputs: minutes, _account.
sms_configA
Get the current SMS/phone number configuration for this agent. Shows whether SMS is enabled, the phone number, and forwarding email.
Inputs: _account.
sms_messagesA
List SMS messages (inbound and outbound). Use direction filter to see only received or sent messages.
Inputs: limit, offset, _account, direction.
sms_parse_emailA
Parse an SMS from a forwarded Google Voice email. Use this when you receive an email from Google Voice containing an SMS. Extracts the sender number, message body, and any verification codes.
Inputs: emailBody (required), _account, emailFrom.
sms_read_voiceA
Get instructions and URL for reading SMS directly from Google Voice web (FASTEST method). Returns the voice.google.com URL and guidance for browser-based SMS reading. Primary method - much faster than email forwarding.
Inputs: _account.
sms_recordB
Record an SMS message read from Google Voice web or any other source. Saves to SMS database and extracts verification codes. Use after reading a message from voice.google.com.
Inputs: body (required), from (required), _account.
sms_sendB
Send an SMS text message. Direct provider configs such as 46elks send through the provider API; Google Voice legacy configs return browser-send instructions.
Inputs: to (required), body (required), _account.
sms_setupC
Configure SMS/phone number access. Supports Google Voice legacy forwarding and direct 46elks provider delivery/webhooks.
Inputs: phoneNumber (required), apiUrl, _account, password, +5 more.
stop_agentA
HARD-stop an agent mid-task WITHOUT deleting it. Sets the agent's stopped flag and (0.9.29+) immediately ABORTS any in-flight worker for that agent — the running SDK call is killed via AbortController, any queued coalesced wakes are dropped, and any deferred rate-limit retries are cancelled. After the stop, the dispatcher refuses to wake the agent for any reason (allowlists, To/Cc, task events all silently no-op). Mail STILL lands in the mailbox, so the email-thread audit trail is preserved. Use this instead of delete_agent when you want to halt a churning sub-agent right now and keep the option to read the thread later or resume it. Resume with resume_agent. Requires master API key.
Inputs: name (required), reason, _account.
storageA
Full database management system for agents. 28 actions: DDL (create/alter/drop/clone/rename tables & columns), DML (insert/upsert/query/aggregate/update/delete/truncate), indexing (create/list/drop/reindex), import/export (JSON/CSV, conflict handling), raw SQL, maintenance (stats/vacuum/analyze/explain), archiving. WHERE supports operators: $gt, $gte, $lt, $lte, $ne, $like, $ilike, $in, $not_in, $is_null, $between. Works on SQLite, Postgres, MySQL, Turso.
Inputs: action (required), set, sql, rows, +31 more.
submit_resultB
Submit the result for a claimed task, marking it as completed
Inputs: id (required), result, _account.
tail_workerA
Tail the log of a running (or recently-finished) dispatcher worker. Use this when check_activity shows a worker has been running a long time or is marked stale, and you want to see what it is actually doing — every tool call, tool result, and assistant chunk is logged as a one-liner. Returns the last N lines (default 80). The workerId comes from check_activity output. Requires master key.
Inputs: workerId (required), lines, _account.
telegram_configA
Get the current Telegram channel configuration for this agent — whether it is enabled, the bot username, linked chats, and transport mode. Credentials are redacted.
Inputs: _account.
telegram_messagesA
List stored Telegram messages (inbound and outbound) for this agent, newest first.
Inputs: limit, chatId, offset, _account, +1 more.
telegram_pollA
Pull and process new Telegram updates (poll-mode transport). Call this on a schedule when the channel is in poll mode to ingest new inbound messages and answer ask_operator questions sent from the operator chat.
Inputs: _account.
telegram_sendA
Send a Telegram message from this agent's bot to a chat. Requires the Telegram channel to be configured (telegram_setup) and enabled.
Inputs: text (required), chatId (required), _account, replyToMessageId.
telegram_setupA
Configure the Telegram channel for this agent — register a bot token from @BotFather and link the chat(s) allowed to message the agent. The token is verified with Telegram and stored encrypted. Defaults to poll mode (call telegram_poll on a schedule); pass mode "webhook" with a public HTTPS webhookUrl + webhookSecret for push delivery.
Inputs: botToken (required), mode, _account, webhookUrl, +3 more.
template_sendB
Send an email using a saved template with variable substitution. Variables like {{name}} are replaced.
Inputs: id (required), to (required), cc, bcc, +3 more.
update_metadataA
Update the current agent's metadata. Merges provided keys with existing metadata.
Inputs: metadata (required), _account.
wait_for_emailA
Block until a matching email (or task) lands in your inbox. Push-based (SSE) — far more efficient than polling. Supports filtering by sender, subject substring, thread (In-Reply-To), or a participants list. The single-most-useful tool for thread-based coordination: send a kickoff email CC'ing your team, then wait_for_email({ subject: "<core thread subject>" }) to wake on the first reply. Non-matching events that arrive during the wait are ignored — you only resume when something you asked for shows up (or timeout).
Inputs: from, subject, timeout, _account, +3 more.
whoamiB
Get the current agent's account info — name, email, role, and metadata
Inputs: _account.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 101 tools
Despite family prefixes, there are many near-duplicate surfaces: send_email vs broadcast_email vs message_agent vs call_agent, mark_read vs batch_mark_read vs batch_read, list_inbox vs inbox_digest vs list_folder, and six overlapping sms_* tools (sms_setup, sms_config, sms_read_voice, sms_record, sms_parse_email, sms_messages). Memory is split across memory, memory_reflect, memory_context, memory_stats and save_thread_memory with unclear boundaries. An agent will frequently mis-pick between these.
Mostly snake_case with a useful family-prefix system (sms_*, media_*, telegram_*, call_*, batch_*), but verb/noun ordering is mixed: some are verb-first (delete_email, send_email, check_health), others noun-first (sms_messages, memory_stats, call_status, phone_capabilities), and a few are bare nouns (storage, memory, invoke, whoami). Readable but not a single predictable pattern.
101 tools is an extreme surface for what is conceptually an email-plus-channels agent. Whole subsystems (media editing, storage DDL, phone missions, domain purchasing) bolt onto the mail core, and request_tools/invoke exist precisely because the list cannot be held in context. Massively over-scoped.
Coverage of the stated domain is genuinely broad: mail CRUD, folders, tags, drafts, scheduling, rules, signatures, templates, relay/domain setup, SMS, phone, Telegram, media, memory and task coordination. Remaining gaps are minor (e.g. no explicit unsubscribe/reputation handling, some setup-only stubs like purchase_domain that cannot actually transact).
Maintenance
Related MCP Connectors
Real email inboxes for AI agents: create inboxes, catch verification codes, extract OTPs, reply.
Email for AI agents: inbox in one call, no signup; codes, links, reply, send; own domains.
Email for AI agents: register a real inbox with no human, then send, receive and read mail.
Task-scoped email inboxes for AI agents: read mail, extract verification codes, and reply.
Related MCP Servers
- AlicenseAqualityBmaintenanceEmail for AI agents. Create inboxes, send and receive emails without phone or CAPTCHA. Inboxes are server-readable, not end-to-end encrypted.21111 npmMIT
- AlicenseAqualityBmaintenanceProvides disposable email inboxes for AI agents to automatically receive and extract OTPs and magic links, enabling seamless email verification during autonomous workflows.3262 npmMIT
- AlicenseAqualityCmaintenanceProvides AI agents with real email infrastructure, enabling them to create inboxes, send/receive messages, and extract verification codes from incoming mail.14MIT
- FlicenseNot gradedqualityBmaintenanceEnables AI agents to autonomously create email accounts, verify domains, send and receive emails, and monitor delivery events without requiring human sign-up or payment.1-