Temporary email for AI agents
An MCP server, a CLI and an agent skill for MoeMail. Your agent creates a mailbox, waits for the verification email, reads the code and deletes the box — over the same API that powers moemail.app.
8 MCP tools · runs with npx, nothing to host · Claude Desktop, Cursor, Claude Code, Codex
Three ways in
MCP server
npx -y @moemail/mcp. Eight tools any MCP client can call, over stdio. Nothing to deploy and nothing to keep running.
CLI
npm i -g @moemail/cli. Nine commands, every one with --json output and meaningful exit codes — built for shell-driven agents and CI jobs.
Agent skill
moemail skill install drops a SKILL.md into Claude Code or Codex, so the agent already knows the create → wait → read → delete workflow before it is asked.
The tools
Names are exactly what the server registers. wait_for_email is the one that makes agents work: it blocks for up to 90 seconds and returns status: "timeout" instead of failing, so the agent simply calls it again.
- create_email
- Create a mailbox; returns its
idandaddress. Lifetime1h,24h,3dorpermanent. - wait_for_email
- Poll until a new message arrives (≤ 90 s per call), or time out gracefully.
- list_messages
- Newest-first list of what a mailbox has received.
- read_message
- Full text and HTML of one message.
- list_emails
- Every mailbox this API key owns.
- send_email
- Reply from the temporary address (needs a send quota).
- delete_message
- Remove one message.
- delete_email
- Remove the mailbox and everything in it.
What a session looks like
The verification-code loop, as the tool calls the agent actually makes: four calls, plus however many polls the mail takes to arrive.
Sign up for the beta at example.com with a throwaway address and tell me the code.
The agent creates a mailbox and types the address into the signup form.
→ create_email { "expiry": "1h" }
← { "id": "k3f…", "address": "x7q2m9@moemail.app", "expiresAt": "…T15:04:05.000Z" }Then it waits. Each poll is one API call; here the mail landed after twelve seconds.
→ wait_for_email { "emailId": "k3f…", "timeoutSec": 90 }
← { "status": "received", "elapsedSec": 12,
"message": { "messageId": "m81…", "from": "no-reply@example.com",
"subject": "Your code is 482913", "receivedAt": "…" } }It reads the message and picks the code out of the body.
→ read_message { "emailId": "k3f…", "messageId": "m81…" }
← { "id": "m81…", "from": "no-reply@example.com", "subject": "Your code is 482913",
"content": "Enter 482913 to finish signing up. …", "html": "…", … }And deletes the box, so nothing is left behind.
→ delete_email { "emailId": "k3f…" }
← { "success": true, "deleted": "k3f…" }Done — the code was 482913. I have deleted the mailbox.
Connect a client
Paste your key where the bullets are. The mcpServers block is identical for Claude Desktop, Cursor and Windsurf; Claude Code and Codex take the same command in their own format.
{
"mcpServers": {
"moemail": {
"command": "npx",
"args": ["-y", "@moemail/mcp"],
"env": {
"MOEMAIL_API_KEY": "mk_••••••••••••"
}
}
}
}{
"mcpServers": {
"moemail": {
"command": "npx",
"args": ["-y", "@moemail/mcp"],
"env": {
"MOEMAIL_API_KEY": "mk_••••••••••••"
}
}
}
}claude mcp add moemail -e MOEMAIL_API_KEY=mk_•••••••••••• -- npx -y @moemail/mcp[mcp_servers.moemail]
command = "npx"
args = ["-y", "@moemail/mcp"]
env = { MOEMAIL_API_KEY = "mk_••••••••••••" }Self-hosting MoeMail? Add MOEMAIL_API_URL pointing at your instance — both packages default to moemail.app.
Or drive it from a shell
Same API, no agent runtime. Every command accepts --json; exit code 1 is a runtime error and 2 is a configuration or auth error, so a script can tell "no mail yet" from "wrong key".
npm i -g @moemail/cli
moemail config set api-key mk_••••••••••••
# 1. a mailbox that lives for an hour
moemail create --expiry 1h --json
# {"id":"k3f…","address":"x7q2m9@moemail.app","expiresAt":"2026-09-02T15:04:05.000Z"}
# 2. block until the verification mail lands (exit 1 on timeout)
moemail wait --email-id k3f… --timeout 120 --json
# {"messageId":"m81…","from":"no-reply@example.com","subject":"Your code is 482913","receivedAt":"…"}
# 3. read it, then clean up
moemail read --email-id k3f… --message-id m81… --json
moemail delete --email-id k3f…Teach the agent once
The CLI ships a skill file. Once installed, Claude Code or Codex reaches for moemail on its own whenever a task needs a throwaway inbox, instead of you explaining the workflow each time.
moemail skill install # auto-detects Claude Code and Codex
moemail skill install --platform claude # ~/.claude/skills/moemail/SKILL.md
moemail skill install --platform codex # ~/.codex/skills/moemail/SKILL.mdKeys, quota and price
Both packages authenticate with a MoeMail API key. Create one in your profile — it is the same key the REST API uses, and it draws on the same monthly quota.
API access is a paid add-on: the default plan has no free call allowance. Buy an API-call pack or a Duke upgrade in the shop with MoeCoin. The web inbox itself stays free, so you can see what the mailboxes do before paying for the API.
Budget for polling: every wait_for_email poll and every CLI wait tick is one call. A typical verification round trip — create, wait, read, delete — is four calls plus the polls.
Frequently asked questions
Give your agent an inbox
Create an API key, paste one block of config, and the next signup flow your agent runs will finish on its own.