DEV Community

Cover image for I Built an MCP Server for Temporary Email — Here's How AI Agents Can Now Handle Email Verification
Diego Ramos
Diego Ramos

Posted on

I Built an MCP Server for Temporary Email — Here's How AI Agents Can Now Handle Email Verification

#ai #mcp #email #typescript

The Problem

If you've ever tried to automate a signup flow with an AI agent, you've hit this wall: the service sends a verification email, and your agent has no way to read it.

The agent can fill out forms, click buttons, navigate pages. But when the flow says "check your email for a verification code," the agent is stuck. You either do it manually, hardcode a test email, or skip email verification entirely in your test environment.

None of those options work well when you want agents to operate autonomously.

What MCP Gives Us

The Model Context Protocol (MCP) is an open standard that lets AI agents call external tools. Instead of the agent guessing or hallucinating, it can call a real API through a structured interface.

I built an MCP server for GoneBox, a free temporary email service, so AI agents can:

  1. Create a disposable inbox on the fly
  2. Wait for an email to arrive
  3. Extract verification codes or confirmation links
  4. Clean up after themselves

All through standard MCP tool calls — no custom integration code needed.

Setup

Add the server to your claude_desktop_config.json:

{
  "mcpServers": {
    "gonebox": {
      "command": "npx",
      "args": ["@gonebox/mcp-server"],
      "env": {
        "GONEBOX_API_URL": "https://api.gonebox.email",
        "GONEBOX_API_KEY": "your-api-key-here"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Same config works for Cursor (.cursor/mcp.json) and Windsurf.

That's it. Restart your client, and the agent now has 7 new tools available.

The Tools

Tool What it does
create_inbox Creates a temp email address (random or custom username)
list_messages Lists all messages in an inbox
read_message Reads the full content of a specific email
wait_for_email Polls until a new email arrives (with optional subject filter)
delete_inbox Permanently deletes inbox and all messages
extract_verification_code Finds 4-8 digit OTP codes in the latest email
extract_link Finds verification/confirmation URLs in the latest email

You get 3 domain choices: gonebox.email, sumiu.email, and nemexiste.email. All work the same way.

Real Workflow: Email Verification

Here's what an actual agent interaction looks like when signing up for a service:

Agent: I'll create a temporary email for the signup.
→ create_inbox(domain: "gonebox.email")
← { "email": "kx7m2p@gonebox.email", "expires_at": "2026-05-20T15:30:00Z" }

Agent: Now I'll fill the signup form with kx7m2p@gonebox.email...
[agent fills the form]

Agent: Waiting for the verification email...
→ wait_for_email(address: "kx7m2p@gonebox.email", subject_contains: "verify", timeout_seconds: 60)
← { "found": true, "waited_seconds": 8, "message": { "subject": "Verify your account", ... } }

Agent: Got it. Let me extract the code.
→ extract_verification_code(address: "kx7m2p@gonebox.email")
← { "found": true, "code": "482916" }

Agent: Entering code 482916...
[agent enters the code]

Agent: Cleaning up the temporary inbox.
→ delete_inbox(address: "kx7m2p@gonebox.email")
← { "deleted": true }
Enter fullscreen mode Exit fullscreen mode

The wait_for_email tool polls every 3 seconds and supports a configurable timeout (5-300 seconds). You can filter by subject to avoid matching unrelated emails.

How extract_verification_code Works

The code extraction isn't just regex-on-a-string. It uses a multi-strategy approach:

  1. Keyword proximity — looks for digits near words like "code", "verify", "OTP", "PIN"
  2. Reverse pattern — catches formats like "482916 is your code"
  3. Context window — for standalone digit sequences, checks if verification keywords appear within 80 characters
  4. Fallback — first standalone 4-8 digit number in the email

It searches the plain text body first, then falls back to HTML. Works with English and Portuguese email templates.

How extract_link Works

Similarly, extract_link scans for URLs containing verification-related path segments: verify, confirm, activate, reset, token, auth, magic-link, invitation, and more.

You can also pass link_contains to filter for specific URL patterns:

→ extract_link(address: "kx7m2p@gonebox.email", link_contains: "reset-password")
← { "found": true, "url": "https://example.com/reset-password?token=abc123" }
Enter fullscreen mode Exit fullscreen mode

Using the REST API Directly

The MCP server is a thin wrapper around the GoneBox REST API. If you're building something that doesn't use MCP, you can call the API directly:

# Create inbox
curl -X POST https://api.gonebox.email/api/v1/inboxes \
  -H "Content-Type: application/json" \
  -d '{"domain": "gonebox.email"}'

# List messages
curl https://api.gonebox.email/api/v1/inboxes/kx7m2p@gonebox.email/messages

# Read a message
curl https://api.gonebox.email/api/v1/messages/msg_abc123

# Delete inbox
curl -X DELETE https://api.gonebox.email/api/v1/inboxes/kx7m2p@gonebox.email
Enter fullscreen mode Exit fullscreen mode

The API runs on Cloudflare Workers with sub-100ms response times globally.

Architecture

The stack is designed around being cheap to operate:

  • Email ingestion: Cloudflare Email Routing (catch-all on 3 domains) feeds into a Worker that parses, sanitizes (DOMPurify), and stores emails
  • Storage: Cloudflare D1 (SQLite at the edge) with automatic TTL cleanup every 5 minutes
  • API: Hono on Cloudflare Workers with KV caching
  • MCP Server: TypeScript, @modelcontextprotocol/sdk, stdio transport, distributed via npm

Inboxes auto-delete after 1 hour. No registration, no login, no personal data stored.

What It Doesn't Do

Being transparent about limitations:

  • No outbound email — GoneBox only receives email. It can't send.
  • No attachments (yet) — attachments are stripped in v1 to keep storage manageable.
  • 1-hour TTL on free tier — inboxes expire automatically.
  • Rate limited — 60 requests/minute without an API key, 10 inboxes/minute per IP.

Why I Built This

Two reasons. First, I was building AI agent workflows and kept hitting the email verification wall. Every temp email service has a web UI, but none had an MCP server.

Second, the MCP ecosystem is still young. There are MCP servers for databases, file systems, web search — but basic infrastructure like email was missing. Temp email is a good fit for MCP because the operations are simple, stateless, and the data is ephemeral by design.

Try It

If you're building AI agent workflows that involve email, give it a try. The MCP server takes about 30 seconds to set up.

Top comments (0)