Email Agent Protocol
Give an AI agent an inbox, hands in your tools, and a home in the cloud — in one 90-minute sprint.
In this protocol you'll deploy a small, production-grade AI agent that you talk to by email. It reads every message sent to its own address, thinks with Claude, optionally reaches into your other apps (Google Calendar to start), and replies on the same thread. Forwarding an email to it counts as a request. You'll ship it on Cloudflare Workers with one click, wire up AgentMail and Composio, and then make it yours by editing a single plain-English file.
Context
The Problem
Most "AI agent" tutorials end where the real work begins. You get a chat box in a browser tab that forgets everything, can't touch your calendar, and has no address anyone can reach. The first twenty minutes of setup decide whether you spend a session building or waiting on confirmation emails — so most people never get past them. An agent that actually earns its keep needs three things: an inbox of its own so it has an identity and a channel people already use, hands in your other tools so it can act instead of advise, and a home in the cloud so it's running when you aren't. This protocol gets you all three, with an allowlist and a kill switch so nothing here is a toy.
Deliverables
What You'll Build
Method
Protocol Steps
Gear Check — Five Accounts, Twenty Minutes
Create the accounts before you build so the session is spent building, not waiting on verification emails. GitHub (code), Cloudflare (hosting), AgentMail (the inbox), Composio (the bridge to your other apps — 20k actions a month free), and an Anthropic API key (the brain — add ~$10 of credit; a session costs pennies). Use the same email for GitHub and Cloudflare. Grab the AgentMail, Composio, and Anthropic keys now and keep them somewhere handy.
Deploy — One Click, Your Own Copy
Click the Deploy to Cloudflare button on the repository. Cloudflare copies the project into your GitHub account and deploys it as a Worker. You get a URL like https://email-agent.YOUR-SUBDOMAIN.workers.dev — visiting it should show `ok`. Copy the URL; you'll need it in step 4. This is the part that tends to surprise people: everybody in the room has a live agent within a few minutes.
Add Your Keys — The Agent's Keyring
In the Cloudflare dashboard: Workers & Pages → email-agent → Settings → Variables and Secrets. Add four secrets: ANTHROPIC_API_KEY (the brain), AGENTMAIL_API_KEY (the inbox), COMPOSIO_API_KEY (the hands), and ALLOWED_SENDERS — your own email address, comma-separated if several. Anyone not on the allowlist is silently ignored; skip it and the agent will happily reply to anyone who finds the address, on your credits. A fifth secret comes out of the next step.
Give It an Inbox — Run the Setup Script
One small script creates the AgentMail inbox and points its webhook at your Worker. Browser route (recommended, nothing to install): open your copy of the repo on GitHub → Code → Codespaces → Create codespace, then in the terminal run `npx tsx scripts/setup.ts https://email-agent.YOUR-SUBDOMAIN.workers.dev`. Laptop route: install Node.js LTS, clone, `npm install`, run the same command. The script prints your agent's email address and a webhook signing secret (whsec_...). Add that as AGENTMAIL_WEBHOOK_SECRET in Cloudflare. Safe to run twice — it never creates duplicates.
Say Hello — Test From Your Phone
Email your agent's address from the account you allowlisted and ask it anything. A reply lands on the same thread in roughly fifteen seconds. To watch it think in real time, run `npx wrangler tail` — the log says exactly what's happening, and if nothing comes back, the most common cause is a sender that isn't on ALLOWED_SENDERS.
Give It Hands — Connect Google Calendar
Ask: "What's on my calendar tomorrow?" The agent replies with a Composio connection link — click it within ten minutes, authorise Google, wait about thirty seconds, and ask again. Now it reads your real calendar instead of guessing. The same flow extends to any Composio toolkit: add slugs like "gmail", "notion", or "github" to the TOOLKITS list in src/agent.ts and redeploy.
Make It Yours — Edit One File
Open src/prompt.ts. Everything the agent knows — its personality, who it works for, your timezone, standing rules like "keep replies under 100 words" — lives in that one file, in plain English. Edit it in your Codespace or directly on github.com, commit, push, and Cloudflare redeploys automatically. Working from a local clone? `npm run deploy`. Use Claude Code in the repo to extend behaviour beyond the prompt (prompts below).
Kill Switch & Plan B
If the agent ever needs to stop immediately: `npm run teardown` disconnects the inbox from the Worker in about two seconds. Mail still arrives; the agent just stops seeing it. Re-running setup reconnects it — and prints a NEW signing secret you must update in Cloudflare. Demo broken mid-session? `npm run local` runs the identical brain on your laptop over a WebSocket with no public URL, reading keys from .dev.vars. Nobody gets left at the put-in.
Get the code
Everything in this protocol ships as a public repository. Deploy your own copy with one click, or read the source and adapt it to your stack.
github.com/Modern-Zen/email-agentUnlock the Protocol
Enter your email to access the full Loom walkthrough, prompt library, infrastructure diagrams, and deployment checklist.
No spam. Unsubscribe anytime. Your email is stored securely.