agenticmail/agenticmail

**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:**
>
>
>
> Zero prompts, ~2 minutes, fully autonomous. For the full runbook (verification, common failures, repo conventions if you're modifying the code), see **AGENTS.md** — the agents.md file at this repo's root.
---
📄 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]](./research/agent-rpc-vs-spawn/paper.pdf) [[Source]](./research/agent-rpc-vs-spawn/)
---
✨ 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, and media_capabilities. Available as MCP media_* tools and OpenClaw agenticmail_media_* tools, both thin clients of new /media/* API routes over a core MediaManager.
- **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 media block on /health and the media_capabilities tool surface what is available.
- **Safe by construction.** Every binary is invoked via execFile with an argument array — no shell, no string interpolation. Untrusted input paths are validated (no control characters, no leading-dash flag-injection, must exist); numeric options are clamped; every call carries a bounded timeout and output buffer; output files land only inside the configured media directory.
✨ What's new in 0.9.54
Twilio joins 46elks as a phone transport provider.
- **Pick your carrier.** PhoneTransportProvider is now 46elks or twilio — 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.json REST API, TwiML webhooks, status-callback cost tracking. Inbound webhooks are verified with the X-Twilio-Signature header (HMAC-SHA1, timing-safe, fail-closed) on top of the per-mission token.
- **Twilio realtime voice.** A Twilio Media Streams ↔ OpenAI Realtime bridge. RealtimeVoiceBridge was generalised behind a RealtimeTransportAdapter seam — one bridge serves both carriers, function-calling / barge-in / transcript logic written once. Twilio audio is G.711 µ-law @ 8 kHz and the OpenAI session uses audio/pcmu, so a Twilio call needs no transcoding. A 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; RealtimeVoiceBridge dispatches the model's function calls through an injected ToolExecutor, returns function_call_output, and keeps the phone line warm during slow tools with a safety-net timeout + an in-flight call cap.
- **ask_operator — human-in-the-loop on a live call.** The agent records an operator query on the mission, notifies the operator (channel-agnostic; default email), polls up to ~5 min, and resumes with the answer. If the caller hangs up while a query is pending, the mission is flagged for **callback-on-disconnect** — once the operator answers, it re-dials with a continuity task.
- **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_operator notifications and approvals.