agenticmail/mcp

Check 🎀 AgenticMail server health status

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.

Check for pending tasks assigned to you (or a specific agent) or tasks you assigned to others

Claim a pending task assigned to you

List or remove inactive non-persistent agent accounts (requires master API key)

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.

Create a new mail folder for organizing emails

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.

Delete an email by its UID

List past agent deletion reports or retrieve a specific report by ID. Shows archived email summaries from deleted agents. Requires master API key.

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.

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.

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.

Get a compact inbox digest with subject, sender, date, flags and text preview for each message. More efficient than listing then reading individually.

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" }).

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.

List messages in a specific folder

List all mail folders/mailboxes

List recent emails in the agent's inbox

List, add, or delete contacts

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.

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.

Manage server-side email rules that auto-process incoming messages (move, tag, mark read, delete).

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").

List, create, or delete email signatures

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.

Create, list, delete tags, tag/untag messages, get messages by tag, or get all tags for a specific message.

List, create, or delete email templates

Mark an email as read

Mark an email as unread

Edit audio: trim, convert format, merge files, adjust volume, change speed, extract from video, reverse, fade in/out. Requires ffmpeg.

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.

Edit an image: resize, crop, rotate, convert format, compress, overlay text, flip, blur, sharpen, grayscale. Requires ImageMagick.

Get metadata about any media file: duration, resolution, codec, bitrate, channels, etc. Requires ffprobe.

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).

List the available text-to-speech voice presets.

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).

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.

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.

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.

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.

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.

Get aggregate statistics about your persistent memory — total entries, breakdown by category / importance / source, and average confidence.

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.

Move an email to another folder (e.g., Trash, Archive)

Show the configured phone provider, caller number, supported regions, and whether realtime media is available.

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).

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).

Read the full content of a specific email by its UID

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"…

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).

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.

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 th…

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.

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 a…

Send a test email through the gateway to verify configuration (requires master API key)

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.

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.

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.

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.

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. Idem…

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.

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.

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.

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`.

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.

Get the current SMS/phone number configuration for this agent. Shows whether SMS is enabled, the phone number, and forwarding email.

List SMS messages (inbound and outbound). Use direction filter to see only received or sent messages.

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.

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.

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.

Send an SMS text message. Direct provider configs such as 46elks send through the provider API; Google Voice legacy configs return browser-send instructions.

Configure SMS/phone number access. Supports Google Voice legacy forwarding and direct 46elks provider delivery/webhooks.

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 …

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.

Submit the result for a claimed task, marking it as completed

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.

Get the current Telegram channel configuration for this agent — whether it is enabled, the bot username, linked chats, and transport mode. Credentials are redacted.

List stored Telegram messages (inbound and outbound) for this agent, newest first.

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.

Send a Telegram message from this agent's bot to a chat. Requires the Telegram channel to be configured (telegram_setup) and enabled.

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.

Send an email using a saved template with variable substitution. Variables like {{name}} are replaced.

Update the current agent's metadata. Merges provided keys with existing metadata.

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).

Get the current agent's account info — name, email, role, and metadata