DEV Community: Francisco Perez

Why Every AI Agent Stack Needs an Email Verification Layer

Francisco Perez — Thu, 30 Apr 2026 19:10:36 +0000

Your agent just submitted a registration form. The third-party service responded with a 200 OK and a message: "Check your inbox for a verification link."

The agent cannot check an inbox. It doesn't have one. It used your dev email address — the one that belongs to a human who is in a different time zone and probably not watching their email right now. The agent is stuck at the wall. The pipeline is stalled. And the frustrating part is that every other step worked.

AI agent email verification is one of the most common hard stops in agentic pipelines. Agents can browse the web, call APIs, fill forms, parse HTML, and chain together dozens of steps — but the moment a service sends a verification email, most of them hit a dead end. This article explains why that happens, what the actual requirements are for email infrastructure that works with agents, and how to wire up a purpose-built MCP email server so it never happens again.

What Changed — From Chatbots to Agents That Actually Do Things

A chatbot suggests. An agent executes.

The distinction matters here. Chatbots operate in a request-response loop with a human at one end. Agents operate in a perceive-reason-act loop that runs autonomously — they navigate UI flows, call external APIs, handle state across steps, and complete tasks without a human approving each action.

The infrastructure that made this practical at scale is Model Context Protocol (MCP), an open standard released by Anthropic and now the de-facto interoperability layer for AI agent tooling. MCP defines a canonical interface for exposing capabilities to agents: a server registers typed tools, and any MCP-compatible runtime — Claude, Copilot, AutoGen, LangGraph, n8n — can discover and call those tools without custom glue code per integration. By 2025-2026, Google, Microsoft, and Amazon had all adopted MCP as a core part of their agent platform strategies.

The practical consequence: an agent without the right tools is just a chatbot with extra steps. Tools are what give agents agency. A browser tool lets the agent navigate. A code execution tool lets it write and run scripts. A search tool lets it query the web. And an email tool — specifically, a purpose-built one that creates real inboxes and reads from them programmatically — is what lets it complete the signup flows, verification steps, and notification-driven workflows that are gated behind email.

Without it, every email-gated flow becomes a manual intervention point. That is the failure mode most teams discover late, usually at 2am when a pipeline that worked in testing falls apart against a real service.

Email Verification Is the Silent Killer of Agentic Flows

Most people underestimate how often email verification appears in real-world automation. Account registration, API key delivery, purchase confirmations, approval workflows, password resets — a significant fraction of services require a working inbox before they grant access to anything.

The problem has four distinct failure modes when you try to handle email without proper infrastructure:

1. The agent must own the inbox before it signs up. You cannot verify an address you do not control. The correct sequence is: create inbox -> get address -> submit form -> wait for email -> extract token. Most agent implementations skip the first step and use the developer's real email address, which collapses the rest of the flow.

2. Using a real email doesn't scale. One inbox shared across all agent runs causes immediate problems: parallel runs contaminate each other's messages, OTP codes from different registrations get mixed up, and your dev account accumulates thousands of verification messages. That is also a privacy and compliance problem — real user email addresses attached to test accounts.

3. Public disposable email services are blocked. Mailinator, YOPmail, and similar consumer tools are blocked by most production services. They also have no API suitable for agents — no authentication, no reliable delivery, no polling interface that code can depend on.

4. IMAP polling is a trap. The approach that seems obvious — connect to Gmail via IMAP, poll for new messages — breaks in an agent context:

# naive approach -- don't do this
import imaplib, time

def wait_for_otp(email, password, timeout=60):
    mail = imaplib.IMAP4_SSL("imap.gmail.com")
    mail.login(email, password)  # your real credentials in agent context
    start = time.time()
    while time.time() - start < timeout:
        mail.select("inbox")
        _, msgs = mail.search(None, "UNSEEN")
        if msgs[0]:
            return parse_otp(msgs[0])  # brittle regex against raw MIME
        time.sleep(5)  # blocking the agent loop for 5 seconds per cycle
    raise TimeoutError("No OTP received")

What's wrong here: real credentials living in the agent's execution context, no inbox isolation between parallel runs, polling blocks the agent loop, IMAP connections are stateful and flaky, and regex against raw MIME breaks on any whitespace change in the email template.

What a Purpose-Built Agent Email Layer Looks Like

The requirements follow directly from how agents work. Missing any one of them creates a failure mode at scale.

Programmatic inbox creation: one API call returns a live email address — no UI, no human step, no waiting.
Scoped TTL: the inbox expires automatically. Thirty minutes is enough for a signup flow. No garbage collection required from the agent.
No polling loops in agent code: the agent calls wait_for_verification_email with a timeout and gets a result when the email arrives.
Native extraction: the tool returns otp_code or verification_link as a structured field. The agent does not write regex or parse MIME.
Inbox isolation: each agent run gets its own inbox. Parallel pipelines do not share state.
MCP-native: the agent uses email as a tool primitive, not a side channel requiring custom adapter code per framework.

The MCP Email Server in Practice

There are two integration paths. You can use the REST API directly from any agent that can make HTTP calls, or the MCP server if your agent runtime supports Model Context Protocol.

Approach A — REST API

import httpx, time

# Step 1: Create a temporary inbox
response = httpx.post(
    "https://uncorreotemporal.com/api/v1/mailboxes",
    headers={"Authorization": "Bearer uct_xxxx"},
    params={"ttl_minutes": 30}
)
inbox = response.json()
email_address = inbox["address"]  # e.g. "mango-panda-42@uncorreotemporal.com"
# inbox also contains: expires_at

# Step 2: Use this address to sign up somewhere
# ... your agent submits the registration form with email_address ...

# Step 3: Poll for the verification email
for _ in range(18):  # up to 90 seconds
    time.sleep(5)
    messages = httpx.get(
        f"https://uncorreotemporal.com/api/v1/mailboxes/{email_address}/messages",
        headers={"Authorization": "Bearer uct_xxxx"},
    ).json()
    # Each message has: id, from_address, subject, received_at, is_read
    unread = [m for m in messages if not m["is_read"]]
    if unread:
        break

# Step 4: Read the full message
msg = httpx.get(
    f"https://uncorreotemporal.com/api/v1/mailboxes/{email_address}/messages/{unread[0]['id']}",
    headers={"Authorization": "Bearer uct_xxxx"},
).json()
# msg contains: body_text, body_html, from_address, subject, received_at

verification_link = extract_url(msg["body_text"])

Approach B — MCP Tools

Add the server to your claude_desktop_config.json:

{
  "mcpServers": {
    "uncorreotemporal": {
      "command": "uvx",
      "args": ["uncorreotemporal-mcp"],
      "env": {
        "UCT_API_KEY": "uct_your_key_here"
      }
    }
  }
}

With the MCP server registered, Claude and other MCP-compatible agents complete the entire verification flow using native tool calls:

# Tool 1: create_signup_inbox
inbox = create_signup_inbox(service_name="github", ttl_minutes=30)
# Returns: {"inbox_id": "mango-panda-42@uncorreotemporal.com",
#           "email": "mango-panda-42@uncorreotemporal.com",
#           "expires_at": "2026-04-30T15:30:00Z"}

# ... agent submits signup form using inbox["email"] ...

# Tool 2: wait_for_verification_email
result = wait_for_verification_email(
    inbox_id=inbox["inbox_id"],
    timeout_seconds=90,
    subject_contains="verify"
)
# Returns: {"status": "received", "message_id": "3f8a1c2b-...",
#           "subject": "Please verify your account"}

# Tool 3a: extract_verification_link
link = extract_verification_link(
    inbox_id=inbox["inbox_id"],
    message_id=result["message_id"]
)
# Returns: {"verification_link": "https://github.com/confirm?token=abc123"}

# Tool 3b: extract_otp_code
otp = extract_otp_code(
    inbox_id=inbox["inbox_id"],
    message_id=result["message_id"]
)
# Returns: {"otp_code": "847291", "candidates": ["847291"]}

Why MCP is cleaner: the agent gets tools as native primitives with typed schemas. No credential management in agent context. No adapter code per framework. There is also a complete_signup_flow tool that wraps the entire sequence in a single call.

Full setup docs: https://uncorreotemporal.com/en/docs/mcp/

Beyond One-Off Testing — Where This Scales

Parallel agent workloads. A pipeline running 50 sub-agents simultaneously needs 50 isolated inboxes, all created programmatically, all expiring on schedule. The Pro plan supports 20 concurrent mailboxes with 2,000 requests/day; the Team plan handles 100 mailboxes at 10,000 req/day. Sized for production agent workloads: https://uncorreotemporal.com/en/pricing/

Privacy by design. Agents acting on behalf of users should never touch real user email addresses. Ephemeral inboxes make this a structural guarantee — the address expires, the data disappears.

Compliance. In regulated industries, test data must not include real PII. An inbox at mango-panda-42@uncorreotemporal.com has no connection to any real person. It expires on schedule. It leaves no trail.

Conclusion

The verification email that stops your agent is not a hard problem — it is a missing infrastructure problem. Add a purpose-built email layer that creates isolated inboxes on demand, waits for delivery without polling loops, and extracts tokens as native tool outputs.

To get started: MCP setup docs at https://uncorreotemporal.com/en/docs/mcp/ — or try the free plan (1 mailbox, 50 req/day) at https://uncorreotemporal.com/en/pricing/

Originally published at uncorreotemporal.com

Agentic Web Email Infrastructure

Francisco Perez — Tue, 28 Apr 2026 20:09:43 +0000

Your agent is three steps away from completing a registration. It filled out the form, submitted it, and got a 200 OK back. The service responds: "Check your inbox for a verification link."

And there the agent stops.

There is no inbox to check. The email address it used was your dev account — the one you use for everything — and that account belongs to a human who is probably asleep. There is no tool the agent can call that returns "the link from the email that just arrived." It has done everything right, and it is stuck.

This is the agentic web email infrastructure problem. Agents can browse pages, call APIs, write code, and run shell commands. But most of them cannot receive email — and an astonishing fraction of real services require email verification before granting any access at all. Until your agent can create an inbox, read from it programmatically, and extract tokens from the messages that arrive, it will keep failing at this wall.

The rest of this article explains why this is architecturally harder than it looks, and what a proper solution requires.

What the Agentic Web Actually Means

The shift happening right now is not about smarter chatbots. It is about systems that follow a complete perceive → reason → act loop without a human approving each step.

In 2026, this is production behavior. GitHub Copilot opens pull requests, runs tests, iterates on reviewer feedback, and merges — end to end without a developer in the loop for each cycle. Google Search can schedule appointments by calling restaurant booking APIs directly. Cloudflare and GoDaddy ship integrations where agents register domains, provision DNS records, and deploy edge workers autonomously. These are not demos. These are workflows that previously required a person sitting at a computer.

The interoperability layer making all of this possible is Model Context Protocol (MCP), an open standard released by Anthropic and now adopted across the industry. MCP defines how agents discover and invoke external tools: a schema-annotated registry of capabilities that any MCP-compatible runtime — Claude, Cursor, AutoGen, LangGraph, n8n — can use without writing custom adapter code for each integration. An agent registers a server, gets a list of typed tools back, and can call them the same way it calls any other capability.

As agents take on more real-world tasks — account provisioning, API access registration, subscription management, collecting data from services that require login — they increasingly hit the same structural blocker. Email-gated flows are not a fringe edge case. They sit at the entrance to most services on the internet, and the agentic web email infrastructure needed to get past them is almost always missing from the stack.

The Email Verification Wall

Email verification is the most common blocker for autonomous agents because the standard flow makes three assumptions that break the moment an agent is involved.

The inbox exists before the signup. A human has an email address before they visit the registration page. An agent must create the inbox first, get the address back, then use that address in the form. The sequence matters: you cannot verify an address you do not already control.

A human is monitoring the inbox. OTP codes expire in minutes. Verification links sometimes expire in hours. The standard UX — sign up, switch to email, click the link — assumes continuous human availability. An agent needs a programmatic flow: create inbox, submit form, poll for the message, extract the token, complete the flow. No human hand-off.

The email address is stable and personal. Using your own dev email for agent-driven signups pollutes your inbox with thousands of verification messages from test runs. It also creates a real privacy risk: your email is now attached to every service account the agent created, forever.

The naive workaround looks like this:

# What most teams try first — and why it fails
import time, requests

EMAIL = "my-dev-account@gmail.com"  # shared across all runs, pollutes inbox

# Submit the signup form
requests.post("https://someservice.com/register", json={"email": EMAIL})

# Wait and hope
time.sleep(30)  # no feedback, brittle in CI/CD, timing is a guess

# No programmatic access to Gmail without a full OAuth setup
# The agent is stuck. The only option is asking a human to check.
print("Please verify manually")  # defeats the purpose entirely

This fails in CI because there is no API to read the inbox. It fails across parallel runs because multiple agents share the same address. It fails against services with short OTP TTLs. And it creates a compliance problem every time a real user email ends up attached to a test account.

What Proper Email Infrastructure Looks Like for an Agent

A production-grade AI agent email solution needs to satisfy six requirements. Missing any one of them creates a failure mode at scale.

1. Programmatic inbox creation. The agent must be able to call an API or MCP tool to create a fresh inbox and get back a live email address. Not a UI, not a manual step — a single function call that returns an address ready to receive SMTP traffic.

2. Configurable TTL. Inboxes should expire automatically. Thirty minutes for a signup flow, twenty-four hours for a batch pipeline. The agent declares intent; the infrastructure enforces cleanup. No garbage collection required from the agent.

3. Sub-200ms delivery notification. An agent polling with a five-second sleep introduces up to five seconds of latency per email retrieval. Real pub/sub delivery — or at minimum a polling endpoint with fresh-data guarantees — is what keeps pipelines fast enough to be useful in CI/CD.

4. OTP and link extraction as native primitives. The agent should not be writing regex against raw email bodies. OTP extraction and verification link extraction should be first-class tool calls that return structured fields — otp_code, verification_link — not raw strings the agent has to parse itself.

5. No shared inboxes. Each agent, each run, each task should own its inbox exclusively. A shared inbox leaks tokens between runs, creates race conditions in parallel pipelines, and mixes data between agents operating at different trust levels.

6. API key scoping. Per-key quotas and team plan rate limits prevent a runaway agent from exhausting the inbox budget for the entire organization. The key belongs to the agent system, not to an individual developer account.

These requirements are what separate infrastructure designed for autonomous agents from a consumer-grade disposable email service that someone hacked into a pipeline.

UnCorreoTemporal in Practice — A Real Agent Flow

UnCorreoTemporal provides an MCP server built specifically for autonomous agent signup flows. Five tools cover the complete flow. Here is a working Python example using the real tool names and field names from the codebase:

import asyncio, json
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
import requests

server_params = StdioServerParameters(
    command="uvx",
    args=["uncorreotemporal-mcp"],
    env={"UCT_API_KEY": "uct_your_api_key_here"}
)

async def complete_signup(service_url: str) -> None:
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # Step 1: Create a temporary inbox (TTL: 30 minutes)
            r = await session.call_tool("create_signup_inbox", {
                "service_name": "example-service",
                "ttl_minutes": 30
            })
            inbox = json.loads(r.content[0].text)
            email    = inbox["email"]      # e.g. "mango-panda-42@uncorreotemporal.com"
            inbox_id = inbox["inbox_id"]   # same value; used to poll for messages

            # Step 2: Submit the signup form with the temporary address
            requests.post(f"{service_url}/register", json={"email": email})

            # Step 3: Wait for the verification email (polls automatically)
            r = await session.call_tool("wait_for_verification_email", {
                "inbox_id": inbox_id,
                "timeout_seconds": 90,
                "subject_contains": "verify"
            })
            waited = json.loads(r.content[0].text)

            if waited.get("status") != "received":
                raise RuntimeError("Verification email did not arrive within timeout")

            message_id = waited["message_id"]

            # Step 4a: Extract OTP code (if the service uses numeric codes)
            r = await session.call_tool("extract_otp_code", {
                "inbox_id": inbox_id,
                "message_id": message_id
            })
            otp_result = json.loads(r.content[0].text)
            otp = otp_result.get("otp_code")  # e.g. "847291"

            # Step 4b: Or extract verification link (if the service uses click-to-verify)
            r = await session.call_tool("extract_verification_link", {
                "inbox_id": inbox_id,
                "message_id": message_id
            })
            link_result = json.loads(r.content[0].text)
            link = link_result.get("verification_link")

            # Step 5: Complete the flow
            if otp:
                requests.post(f"{service_url}/verify", json={"otp": otp})
            elif link:
                requests.get(link)

asyncio.run(complete_signup("https://someservice.com"))

The MCP server handles all the infrastructure: creating the mailbox via POST https://uncorreotemporal.com/api/v1/mailboxes, polling for delivery, and extracting structured tokens from the raw email body. The agent just calls tools.

Why This Matters Beyond Testing

The most obvious use case is CI/CD: integration tests that need a fresh inbox per run, per test case, with zero shared state. But the same infrastructure applies to production agent architectures.

Multi-agent pipelines. A research agent, a scheduling agent, and a delivery agent in the same pipeline may each need separate accounts on different services. Each gets its own inbox, its own identity. No cross-contamination between tasks.

Privacy-preserving agent architectures. An agent acting on behalf of a user should never expose that user's real email address to third-party services. Temporary inboxes decouple the user's identity from the agent's operational identity.

Regulatory compliance. Agents that register accounts using real user emails attach PII to every service they touch. Using ephemeral inboxes keeps PII out of third-party data stores — directly relevant to GDPR, CCPA, and any compliance framework that tracks where user data flows.

Scale. One hundred parallel agents each completing a signup flow simultaneously need one hundred isolated inboxes, created and expired programmatically. There is no manual coordination approach that works at that scale.

Conclusion

The agentic web email infrastructure problem is not going away — it is growing proportionally with agent capability. The five MCP tools covered here — create_signup_inbox, wait_for_verification_email, get_latest_email, extract_otp_code, extract_verification_link — cover the majority of real agent email workflows without requiring the agent to manage SMTP, parse raw message formats, or write custom extraction logic.

Get the MCP server running in minutes at uncorreotemporal.com/en/docs/mcp/, or start with a free plan at uncorreotemporal.com/en/pricing/.

Originally published at uncorreotemporal.com/blog/agentic-web-autonomous-agents-email-infrastructure

Why AI Agents in n8n Fail on Real-World Workflows (and How to Fix It)

Francisco Perez — Sun, 19 Apr 2026 13:38:04 +0000

The Gap Between the Demo and the Real World

The demo always works. You wire up an LLM node in n8n, chain a few HTTP requests, and the agent navigates through a multi-step workflow without a hitch. Then you point it at something real — a signup flow, a SaaS trial, a service that requires email verification — and the workflow halts.

Not because the reasoning was wrong. The agent chose the right action. It decided to create an account. It selected the right form fields. It even generated a valid request.

It failed because the service sent a verification email and the agent had no way to receive it.

This is the pattern that breaks most real-world n8n agent pipelines: they are designed for deterministic, synchronous systems, but the real web is asynchronous and email-dependent.

The Promise of n8n + AI Agents

n8n is a genuinely strong orchestration layer. It handles node chaining, branching, retries, credential management, and webhook ingestion cleanly. When you connect it to an LLM via the AI Agent node, you get a workflow that can reason about inputs, call external APIs, and decide what to do next.

This combination works well for:

Scraping structured data and transforming it
Calling APIs with conditional logic
Generating content from templates or user inputs
Classifying and routing incoming data

The LLM handles ambiguity. n8n handles orchestration. For many workflows, this is enough.

The problem surfaces when the workflow leaves the API-accessible world and enters real-world system interactions — specifically, anything that routes through email.

Where Things Break

Email verification is the most common hard wall. Consider any of the following:

Account registration on a third-party service that requires email confirmation before the account is active
OTP-based login where a time-limited code arrives in an inbox
Magic link authentication, where the session token is delivered via email
Trial onboarding flows that gate API key generation behind an email confirmation step

These are not edge cases. They are standard authentication patterns across most of the web. An agent that cannot handle them cannot operate autonomously in real environments.

The deeper problem is structural. Email delivery is asynchronous. The time between a signup request and the arrival of a verification email is non-deterministic — it could be two seconds or forty-five. There is no webhook you can register. There is no polling endpoint you can call against the sender. The email arrives at an inbox, and something needs to be watching that inbox.

In a standard n8n workflow, there is nothing watching.

A Concrete Example: Agent Gets Stuck

Imagine an n8n workflow where an AI agent is tasked with registering a trial account on a data API service to test a new integration:

[AI Agent Node]
  -> decides: "I need to create a test account on api.someservice.com"
  -> calls: POST /api/v1/signup  { email: ???, name: "Test Agent" }
  -> receives: { status: "pending", message: "Check your email to verify" }
  -> next step: ???

The agent needs an email address to register. If you hardcode your personal inbox, the verification email lands in a human mailbox — someone has to click the link manually. The workflow is no longer autonomous.

The typical workarounds developers try:

# Option 1: Use a static dummy address
# -> verification never arrives, account stays unconfirmed

# Option 2: Use a public throwaway service (Guerrilla Mail, temp-mail.org)
# -> no API, browser-only, no way to read messages programmatically

# Option 3: Use Gmail + polling via OAuth
# -> requires OAuth setup, scopes, token refresh, high latency,
#   and you're mixing test email with real email

# Option 4: Give up and inject a pre-verified account
# -> the workflow is no longer testing what it claims to test

None of these are real solutions. They either break automation or introduce manual steps that defeat the purpose of the agent.

Root Cause Analysis

The failure has four technical causes:

1. Async delivery with no callback. Email follows a push model — the sender's SMTP server delivers to a recipient's MX record. There is no mechanism for the receiving side to signal "I got it" back to the sender in a structured way. The gap between send and receive is real and variable.

2. Polling requires infrastructure. To poll an inbox programmatically, you need a mailbox that exposes a REST interface. Standard IMAP is available for personal accounts, but requires OAuth flows, credential management, and careful scope handling. It is not agent-friendly.

3. Unstructured content. Even when you can receive an email, extracting the OTP or verification link requires parsing free-form text or HTML. Services do not follow a standard. One sends Your code is: 482910. Another buries the link in three layers of tracking redirects inside <a> tags. You need extraction logic per-sender or a general-purpose parser.

4. No ephemeral inbox primitive. Agents need disposable, programmatically-controlled inboxes that can be created on demand, pointed at a specific signup flow, read via API, and discarded. No standard infrastructure provides this at the level of a simple REST call.

The Fix: Programmable Inboxes With Structured Extraction

The conceptual fix has three parts:

Create an inbox on demand — an address that is real (routes actual SMTP traffic) and accessible via REST API without OAuth or manual setup
Wait for email with a timeout — poll the inbox until a message arrives or a deadline is reached
Extract structured data — pull the OTP or verification link from the body in a way the next workflow node can consume

This turns an asynchronous, infrastructure-heavy problem into a synchronous, API-driven one. From the perspective of the n8n workflow, email becomes just another HTTP call.

Practical Implementation

Here is how this works end-to-end using the uncorreotemporal.com API, which exposes real SMTP inboxes over REST.

Step 1 — Create an inbox:

curl -X POST "https://uncorreotemporal.com/api/v1/mailboxes?ttl_minutes=30"

Response:

{
  "address": "mango-panda-42@uncorreotemporal.com",
  "expires_at": "2026-04-18T23:04:00.000000+00:00",
  "session_token": "q7Qq...long_token...1Q"
}

Use address as the email in your signup request. The session_token is what authenticates subsequent reads.

Step 2 — Poll for the verification email:

import re
import time
import requests
from urllib.parse import unquote

BASE = "https://uncorreotemporal.com/api/v1"
address = "mango-panda-42@uncorreotemporal.com"
headers = {"X-Session-Token": "q7Qq...long_token...1Q"}

# Poll until a matching message arrives (up to ~150 seconds)
msg_id = None
for _ in range(30):
    r = requests.get(
        f"{BASE}/mailboxes/{address}/messages",
        headers=headers,
        params={"limit": 20},
    )
    r.raise_for_status()

    target = next(
        (m for m in r.json() if "verify" in (m.get("subject") or "").lower()),
        None,
    )
    if target:
        msg_id = target["id"]
        break

    time.sleep(5)

if not msg_id:
    raise RuntimeError("Verification email did not arrive within timeout")

Step 3 — Extract the link or OTP:

# Fetch the full message
r = requests.get(f"{BASE}/mailboxes/{address}/messages/{msg_id}", headers=headers)
r.raise_for_status()
body = r.json()

content = (body.get("body_text") or "") + "\n" + (body.get("body_html") or "")

# Extract verification link
url_match = re.search(r"https?://[^\s\"'<>]+confirm[^\s\"'<>]*", unquote(content))

# Or extract OTP
otp_match = re.search(r"\b\d{4,8}\b", content)

verification_url = url_match.group(0) if url_match else None
otp_code = otp_match.group(0) if otp_match else None

In n8n, this maps directly to:

An HTTP Request node to create the inbox and get address + session_token
A Loop + Wait pattern with an IF node checking for incoming messages
A Code node doing the regex extraction
The next node consuming verification_url or otp_code

The workflow stays headless. No human inbox involved.

The Real Problem Is Not Reasoning

There is a tendency to attribute agent failures to model quality. The agent "hallucinated," it "misunderstood" the task, it "made a wrong decision."

In the cases described above, the model is not at fault. It reasoned correctly. It identified the right action. It issued the right API call. What failed was the absence of infrastructure to complete that action.

AI agents fail on real-world workflows not because of bad reasoning, but because the interfaces they need to interact with — email inboxes, async callbacks, unstructured content — do not expose a clean, synchronous API. The agent cannot be smarter than the tools it has access to.

Fixing this means treating email as a first-class infrastructure primitive in agent workflows, the same way you treat databases, HTTP APIs, or queues. It requires real inboxes, real SMTP delivery, and a REST interface that agents can call without human intermediaries.

Conclusion

Most gaps in real-world agent performance trace back to the same root: the world is not fully API-accessible. Email is the most common example, but the pattern applies anywhere a workflow depends on an asynchronous external event that the agent cannot observe directly.

The good news is that the infrastructure problem is solvable. Once email becomes a programmable, API-accessible layer, a whole class of workflows — account registration, OTP retrieval, verification flows — becomes automatable without manual intervention.

The more interesting question is: what other asynchronous interfaces are your agents currently hitting a wall on, and is the bottleneck the model or the missing infrastructure?

If you want to explore programmable email for your agent workflows, the REST API is documented at uncorreotemporal.com.

AI Agents Need Real Email Infrastructure

Francisco Perez — Fri, 17 Apr 2026 03:17:18 +0000

The Paradox at the Heart of AI Automation

An AI agent can browse the web, write code, summarize a 300-page PDF, and call APIs on your behalf. It can reason through multi-step problems and generate plans that would take a human hours to produce.

Ask it to create an account on a SaaS platform and it stalls. Not because the task is complex — but because the platform sends a confirmation email, and the agent has no inbox.

This is the gap nobody talks about. AI agents are getting smarter every week, but they still can't complete one of the most basic flows in modern software: email-gated account creation. The intelligence is there. The infrastructure is missing.

The Real Problem: Email Is a Gate, Not a Feature

Email verification is not optional in production systems. It is the primary identity checkpoint for:

Account creation — nearly every SaaS platform requires a confirmed email before granting access
OTP verification — two-factor authentication, magic link login, password reset flows
Transactional onboarding — license keys, trial activation, API credential delivery
Subscription confirmation — billing platforms send confirmation links before activating accounts

When an AI agent needs to interact with any of these systems autonomously, it faces a structural problem. It lacks:

Identity — agents don't have their own email address by default. They borrow one, which creates collisions when running parallel tasks or test suites.

Inboxes — even if you hand an agent an email address, it needs programmatic access to read what arrives. Human inboxes (Gmail, Outlook) require OAuth flows and UI scraping. Neither is designed for machines.

Persistence — the agent needs to know when the email arrives, not just poll indefinitely. Real-time notification matters. Polling with backoff on a consumer webmail service is fragile at best.

Without these three things, any agent that touches email-gated systems is blocked at the first gate.

Current Workarounds (And Why They Fail)

Developers have been improvising solutions for years. None of them are production-grade.

Mocks and stubs skip email delivery entirely in tests. They pass locally and fail in staging because no real SMTP path is exercised. You ship a broken confirmation flow and find out when a user reports it.

Shared inboxes (a team Gmail or a catch-all alias) work for manual testing. They break immediately when multiple agents or test workers run in parallel. Message routing is ambiguous — you cannot guarantee which worker reads which email. And shared inboxes accumulate thousands of messages that have to be manually pruned.

Consumer disposable email services like Mailinator or Guerrilla Mail have no real API. They expose a web UI. To automate them, you need a scraper on top of a scraper — fragile, rate-limited, and frequently blocked by platforms as known spam domains.

Manual flows don't scale. If your CI pipeline needs to verify email-based signup 50 times a day, you cannot have a human in the loop.

The pattern is always the same: workaround works locally, breaks under load, breaks under parallelism, breaks when the target platform updates its UI.

Key Insight: Email Is Not UI. It's Infrastructure.

This is the framing shift that matters.

Most developers treat email verification as part of the user experience — a UI concern, something to mock in tests and tolerate in production. But email is a protocol. SMTP has been running since 1982. It is infrastructure in the same sense that DNS or TCP/IP is infrastructure.

When you need to interact with a system that uses email as a control plane — and virtually every SaaS platform does — you need an email layer that behaves like infrastructure:

Addressable: you can create and destroy addresses on demand
Observable: you can receive events when mail arrives, not just poll
Authenticated: access is controlled per inbox, not shared
Ephemeral: addresses expire cleanly so you don't accumulate noise
Programmable: the entire lifecycle is driven by an API, not a browser

Consumer disposable email services are none of these things. A real temporary email API is all of them.

How uncorreotemporal.com Solves This

uncorreotemporal.com is a programmable disposable email API built as infrastructure from the ground up. The architecture has four layers that work together:

SMTP ingestion — a real SMTP server built on aiosmtpd that receives actual email on port 25. Not a webhook relay, not a polling scraper. When a platform sends a confirmation email, it lands via standard SMTP delivery.

FastAPI backend — an async REST API (FastAPI + SQLAlchemy 2.0 async + PostgreSQL) that manages mailbox lifecycle. You create, read, and delete mailboxes through HTTP endpoints. Mailboxes are per-owner, quota-enforced by plan, and isolated from each other.

Real-time WebSocket stream — when mail arrives, a Redis pub/sub event is published to the channel mailbox:{address}. Any client subscribed to WS /ws/inbox/{address} receives a {"event": "new_message", "message_id": "uuid"} notification immediately. No polling required.

Background expiry loop — core/expiry.py runs an async loop every 60 seconds that marks expired mailboxes is_active=False. Expiration is deterministic: you set the TTL when you create the inbox, and it expires on schedule.

MCP server — an MCP server (FastMCP) that wraps the entire email flow as tools for AI agents. Tools include create_signup_inbox, wait_for_verification_email, get_latest_email, extract_otp_code, extract_verification_link, and complete_signup_flow. An agent can complete the entire verification cycle in one tool call.

A Real Example: AI Agent Completing an Email Signup Flow

Here is a working Python example using the REST API directly. This is the same flow the MCP complete_signup_flow tool executes internally.

import time
import httpx
import re

BASE_URL = "https://uncorreotemporal.com"
API_KEY = "your-uct-api-key"

headers = {"Authorization": f"Bearer {API_KEY}"}

# Step 1: Create a temporary inbox
resp = httpx.post(f"{BASE_URL}/api/v1/mailboxes", headers=headers)
resp.raise_for_status()
mailbox = resp.json()

email = mailbox["address"]
expires_at = mailbox["expires_at"]
print(f"Inbox created: {email} (expires: {expires_at})")

# Step 2: Use this address to sign up somewhere
print(f"Using {email} to sign up on the target platform...")

# Step 3: Poll for the verification email
message_id = None
for attempt in range(30):  # 90 seconds max
    time.sleep(3)
    resp = httpx.get(
        f"{BASE_URL}/api/v1/mailboxes/{email}/messages",
        headers=headers,
    )
    messages = resp.json()
    if messages:
        message_id = messages[0]["id"]
        print(f"Email arrived: {messages[0]['subject']}")
        break

if not message_id:
    raise RuntimeError("Verification email did not arrive within timeout")

# Step 4: Read the full message
resp = httpx.get(
    f"{BASE_URL}/api/v1/mailboxes/{email}/messages/{message_id}",
    headers=headers,
)
message = resp.json()
body = message.get("body_text") or message.get("body_html") or ""

# Step 5: Extract OTP or confirmation link
otp_match = re.search(r"\b(\d{4,8})\b", body)
link_match = re.search(r"https?://[^\s"'<>]+confirm[^\s"'<>]+", body)

if otp_match:
    print(f"OTP extracted: {otp_match.group(1)}")
if link_match:
    print(f"Verification link: {link_match.group(0)}")

# Step 6: Clean up
httpx.delete(f"{BASE_URL}/api/v1/mailboxes/{email}", headers=headers)
print("Inbox deleted.")

This is a full, copy-paste ready implementation. The same logic runs inside the MCP complete_signup_flow tool — but from the agent's perspective, the entire flow collapses to a single tool call:

# Via MCP (for Claude, GPT-4 tools, or any MCP-compatible agent)
result = await mcp.complete_signup_flow(
    service_name="github",
    timeout_seconds=90,
)

print(result["email"])              # the inbox address used
print(result["verification_link"])  # extracted confirmation URL
print(result["otp_code"])           # extracted numeric code if present

The MCP tool handles inbox creation, waiting, reading, extraction, and returns a structured result. The agent never touches the email protocol directly.

Why This Matters for AI Agents Specifically

The shift toward autonomous AI agents changes what infrastructure means.

When a human uses a SaaS tool, they provide their identity: their email, their phone, their browser session. The system is designed for a single authenticated human interacting over time.

When an AI agent uses a SaaS tool, it needs to provision identity on demand. It may need to sign up for ten accounts in parallel, verify each one, complete onboarding, and then discard the accounts. It may need to run this flow in CI every night. None of this maps to a human identity model.

Email gives agents an identity layer that is:

Ephemeral by design — temporary inboxes expire automatically, leaving no permanent footprint
Parallel-safe — each run gets its own isolated inbox with its own authentication token
Programmatically observable — the agent can subscribe to real-time events instead of polling
Compatible with real systems — because it uses standard SMTP, every platform that sends email will work

This is not about teaching agents to use email like a human. It is about giving agents access to email as infrastructure — the same way they have access to HTTP clients, databases, and file systems.

Developer Use Cases

The immediate applications are practical and concrete.

CI/CD email testing — your pipeline creates a real inbox, triggers a signup flow on staging, reads the confirmation email, and asserts on the link format or OTP structure. No shared accounts, no mocked delivery. The test exercises the real SMTP path.

End-to-end testing with Playwright or Selenium — browser automation scripts that need to complete signup flows can receive real emails. The test gets a fresh inbox per run, uses the address in the form, reads the verification email, and clicks the link.

AI agent onboarding flows — an agent tasked with "create an account on platform X and retrieve the API key" can complete the full flow autonomously: inbox creation, signup form submission, email reading, OTP entry, API key extraction.

Automated scraping with auth — data collection pipelines that require account creation at each target site. Each run gets a fresh identity and a fresh inbox.

Parallel test isolation — multiple test workers run simultaneously without shared state. Each worker creates its own mailbox, verifies against it, and deletes it. No race conditions, no message routing ambiguity.

Agent-assisted QA — QA automation agents that verify transactional email content (formatting, links, subject lines) as part of a deployment gate. Every deploy triggers a full email lifecycle check.

Conclusion

The current conversation about AI agents focuses almost entirely on reasoning capability: how well the model understands instructions, how reliably it uses tools, how it handles ambiguity. That is the right conversation to have — but it is incomplete.

Agents fail not just because they reason poorly. They fail because they cannot interface with real-world systems that require an identity to function. Email verification is not an edge case. It is the default access control mechanism for virtually every SaaS platform on the internet.

The solution is not to mock it away or build brittle scrapers on top of consumer disposable email services. The solution is to treat email as infrastructure — addressable, observable, authenticated, and ephemeral — and expose it through an API that agents can call directly.

AI agents do not need more intelligence to complete an email signup flow. They need a real inbox.

uncorreotemporal.com is that inbox.

How to Test Email Signup Flows in CI/CD Pipelines

Francisco Perez — Mon, 30 Mar 2026 22:19:52 +0000

The Pain Every CI Pipeline Knows

It works locally. The signup form submits, the confirmation email arrives in your inbox, you paste the OTP, it verifies. Ship it.

Then CI runs. The test sends the signup request, polls... and times out. Or worse: it passes because you mocked the email sender and never actually tested that the email arrives, renders correctly, or contains a working code.

Email signup flows break in CI for a handful of predictable reasons:

Shared inboxes — two parallel test runs both register and poll the same address. Whichever test gets the email first passes; the other times out.
Mocked senders — you assert that send_email() was called, not that an email was received. Template bugs, SMTP credential expiry, and malformed links all pass through silently.
Brittle fixtures — hardcoded email addresses that accumulate stale messages across runs.
No isolation — there's no API to create a fresh inbox per test run, so you bolt on a shared test account and cross your fingers.

The fix is not a better mock. It's a real, isolated, programmable inbox that your test owns for its lifetime.

Quick Start

All examples in this article are from the temporary-email-api-examples repo. The python-example/ folder is a single-file script that demonstrates the full flow with plain requests — no extra libraries required.

Set two environment variables before running:

export UCT_API_BASE_URL="https://uncorreotemporal.com/api/v1"
export UCT_EMAIL_API_KEY="your_api_key_here"

Then:

git clone https://github.com/francofuji/temporary-email-api-examples
cd temporary-email-api-examples/python-example
pip install requests
python main.py

You will see a temporary inbox created, a polling loop start, and — once you trigger a real email to the address — an OTP extracted and printed.

The Flow: Create Inbox - Wait for Email - Extract OTP

The pattern is three steps. Here is how the example implements each one.

1. Create the Inbox

import os, requests

API_BASE_URL = os.getenv("UCT_API_BASE_URL")
API_KEY = os.getenv("UCT_EMAIL_API_KEY")
HEADERS = {"X-API-Key": API_KEY}

create_resp = requests.post(f"{API_BASE_URL}/inboxes", headers=HEADERS, timeout=10)
create_resp.raise_for_status()

inbox = create_resp.json()
inbox_id = inbox.get("id")

One POST, one inbox. No signup flow, no shared state. The inbox_id is the key you use for the next two steps.

2. Poll for Messages

import time, re

pattern = re.compile(r"\b(\d{6})\b")
start_time = time.time()

while True:
    if time.time() - start_time > 60:
        raise SystemExit("Timed out waiting for OTP")

    try:
        msg_resp = requests.get(
            f"{API_BASE_URL}/inboxes/{inbox_id}/messages",
            headers=HEADERS,
            timeout=10,
        )
        if msg_resp.status_code >= 500:
            time.sleep(3)
            continue
        msg_resp.raise_for_status()
        messages = msg_resp.json()
    except requests.RequestException as exc:
        print(f"Request failed: {exc}. Retrying...")
        time.sleep(3)
        continue

    if not messages:
        time.sleep(3)
        continue

The loop handles three distinct cases: server errors (5xx, which you retry), request failures (network blips), and an empty inbox (normal while waiting). Separating these is what makes polling reliable in CI — you don't bail on transient failures.

3. Extract the OTP

    body = messages[0].get("body", "")
    match = pattern.search(body)
    if match:
        otp = match.group(1)
        print(f"OTP found: {otp}")
        break

The regex \b(\d{6})\b matches any standalone 6-digit sequence. Adjust the pattern to match your application's format.

CI/CD Tips

Set an explicit timeout and fail loudly. The example uses 60 seconds. In CI, an infinite loop or a silently hanging test is worse than a hard failure. If the email doesn't arrive in 60 seconds, something upstream is broken — raise, don't sleep forever.

Use fixed poll intervals, not adaptive backoff. Poll every 3 seconds. Predictable timing makes failures easier to diagnose.

Handle 5xx separately from 4xx. A 500 from the messages endpoint is probably transient. A 401 or 404 means your credentials or inbox ID are wrong — retrying won't help. The example retries 5xx and raises immediately on 4xx via raise_for_status().

Don't share inbox IDs across test cases. Create one inbox per test run.

Store credentials in CI secrets, not in code.

# GitHub Actions
env:
  UCT_API_BASE_URL: ${{ vars.UCT_API_BASE_URL }}
  UCT_EMAIL_API_KEY: ${{ secrets.UCT_EMAIL_API_KEY }}

Why This Works in CI

Most email testing approaches fail in CI because they depend on something external: a shared inbox, a stubbed SMTP server, or a hardcoded test account that accumulates state across runs.

This approach is stateless from the pipeline's perspective. Each run calls POST /inboxes, gets a fresh address and ID back, and owns that inbox exclusively until the test exits or the TTL expires. There's nothing to clean up, nothing to coordinate between parallel jobs, and no leftover messages from a previous run to confuse the polling logic.

The inbox also receives real SMTP delivery — the same delivery path your production email goes through. If your email provider is down, your template is broken, or your SMTP credentials expired, the test will fail. That's the point. A test that can't catch those failures isn't testing email; it's testing whether your mock function was called.

Conclusion

Email signup testing is broken in most CI pipelines not because it's technically hard but because the default tools — mocks, shared inboxes, SMTP dev servers — don't give you the properties you need: isolation, real delivery, and an API to read the result programmatically.

The pattern in this article is straightforward: create a dedicated inbox per test, poll for the message with a hard timeout, extract the OTP or link, and proceed. The Python example is a working implementation you can drop into any pipeline today.

Next steps:

Browse the full temporary-email-api-examples repo for Node.js, shell/cURL, Playwright, and pytest examples
Get your API key at uncorreotemporal.com
Wrap the flow in a pytest fixture for per-test inbox isolation in larger test suites

Playwright + Temporary Email API: Full E2E Auth Flow Testing

Francisco Perez — Wed, 25 Mar 2026 02:23:35 +0000

The Problem with Testing Email Auth Flows

Most Playwright suites stop at the form submission. The test fills the email field, clicks Submit, asserts a success banner, and calls it a day. But the auth flow doesn't end there — it ends when the user clicks the link in their inbox. That second half is invisible to your test.

The common workarounds all have the same failure mode in disguise:

Mocking the email sender — you assert that sendEmail() was called, not that an email was received, rendered correctly, and contains a working link.
Shared test inboxes — two parallel CI runs both register and poll the same inbox. The first email gets consumed by whichever test polls first. Flaky tests guaranteed.
Hardcoded OTP bypass routes — test backdoors that sooner or later end up in a production build.
Mailhog / Mailpit — one more container to deploy, a different API surface from production, and zero validation of your real SMTP path.

The issue isn't test tooling. It's the assumption that email delivery is a side effect you can safely skip or stub. In practice, your verification link can be malformed, your SMTP credentials can expire, your template can break — and a mocked test will pass through all of it.

What We Will Build

By the end of this article you will have a fully working TypeScript Playwright test that:

Creates a temporary inbox via the uncorreotemporal.com API
Submits a signup form using that inbox address
Polls for the incoming email with a configurable timeout
Extracts the OTP code or verification link from the message body
Completes the auth flow inside Playwright
Cleans up the inbox in teardown

The test uses real SMTP delivery — your application sends to the temporary inbox exactly as it would send to a real user. No interceptors, no stubs.

Architecture Overview

[Your App] --signup form--> [FastAPI / Node backend]
                                    |
                              sends real email via SMTP
                                    |
                                    v
                         [uncorreotemporal.com SMTP receiver]
                                    |
                               stores message
                                    |
                  +------------------------------------------+
                  |  REST API: GET /api/v1/mailboxes/        |
                  |           {address}/messages             |
                  +------------------------------------------+
                                    |
                             Playwright test
                            polls -> extracts -> continues

The temporary inbox acts as a controllable endpoint on the SMTP receive side. You created it with one HTTP call; you read from it with another; you tear it down when the test is done. The application under test never knows the difference.

Setup

Install Playwright

npm install --save-dev @playwright/test
npx playwright install chromium

Environment Variables

# .env.test (never commit this)
UCT_API_KEY=uct_your_key_here
DEMO_BASE_URL=http://localhost:3000   # your app under test

Get your API key at uncorreotemporal.com. The free tier is sufficient for local development; for parallel CI pipelines use a paid key with higher inbox quotas.

Playwright Config

// playwright.config.ts
import { defineConfig } from "@playwright/test";

export default defineConfig({
  testDir: "./tests",
  timeout: 60_000,
  workers: process.env.CI ? 4 : undefined,
  use: {
    headless: true,
    baseURL: process.env.DEMO_BASE_URL ?? "http://localhost:3000",
  },
});

Step-by-Step Implementation

Step 1 — Create an Inbox via API

// tests/helpers/email.ts

const BASE = "https://uncorreotemporal.com/api/v1";

interface Inbox {
  address: string;
  expires_at: string;
  session_token: string;
}

export async function createInbox(ttlMinutes = 15): Promise<Inbox> {
  const res = await fetch(`${BASE}/mailboxes`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": process.env.UCT_API_KEY!,
    },
    body: JSON.stringify({ ttl_minutes: ttlMinutes }),
  });

  if (!res.ok) {
    throw new Error(`Failed to create inbox: ${res.status} ${await res.text()}`);
  }

  return res.json();
}

The response:

{
  "address": "crisp-falcon-77@uncorreotemporal.com",
  "expires_at": "2026-03-24T15:00:00+00:00",
  "session_token": "dGhpcyBpcyBhIHNhbXBsZSB0b2tlbg"
}

Step 2 — Use the Inbox in the Signup Form

test("signup -> email verification -> dashboard", async ({ page }) => {
  const inbox = await createInbox();

  try {
    await page.goto("/register");
    await page.fill('[name="email"]', inbox.address);
    await page.fill('[name="password"]', "Secure1234!");
    await page.click('[type="submit"]');

    await page.waitForURL("**/confirm**");
    await expect(page.locator("h1")).toContainText("Check your email");

    const email = await waitForEmail(inbox.address, inbox.session_token);
    // ... extract and complete
  } finally {
    await deleteInbox(inbox.address, inbox.session_token);
  }
});

Step 3 — Wait for the Email (Polling with Retry)

export async function waitForEmail(
  address: string,
  sessionToken: string,
  options: { timeout?: number; interval?: number; subjectFilter?: string } = {}
): Promise<FullMessage> {
  const { timeout = 30_000, interval = 2_000, subjectFilter } = options;
  const encoded = encodeURIComponent(address);
  const headers = { "X-API-Key": process.env.UCT_API_KEY! };
  const deadline = Date.now() + timeout;

  while (Date.now() < deadline) {
    let messages: MessageSummary[];

    try {
      const res = await fetch(`${BASE}/mailboxes/${encoded}/messages`, { headers });
      if (!res.ok) throw new Error(`HTTP ${res.status}`);
      messages = await res.json();
    } catch (err) {
      console.warn(`[waitForEmail] poll error: ${err}. Retrying...`);
      await sleep(interval);
      continue;
    }

    const match = subjectFilter
      ? messages.find((m) => m.subject.toLowerCase().includes(subjectFilter.toLowerCase()))
      : messages[0];

    if (match) {
      const res = await fetch(`${BASE}/mailboxes/${encoded}/messages/${match.id}`, { headers });
      if (!res.ok) throw new Error(`Failed to fetch message body: ${res.status}`);
      return res.json();
    }

    await sleep(interval);
  }

  throw new Error(`[waitForEmail] No email arrived at ${address} within ${timeout}ms`);
}

Key design: network errors are retried, not propagated. "No message" means keep polling — not failure. Use subjectFilter when your app sends multiple emails per registration.

Step 4 — Parse the Email (OTP and Link Extraction)

export function extractOTP(message: FullMessage): string {
  const sources = [message.body_text, message.body_html].filter(Boolean) as string[];
  for (const content of sources) {
    const match = content.match(/\b(\d{6})\b/);
    if (match) return match[1];
  }
  throw new Error("OTP not found in email body");
}

export function extractVerificationLink(message: FullMessage, urlPrefix: string): string {
  const pattern = new RegExp(`${escapeRegex(urlPrefix)}[^\\s"'<>]+`);
  const sources = [message.body_text, message.body_html].filter(Boolean) as string[];
  for (const content of sources) {
    const match = content.match(pattern);
    if (match) return match[0];
  }
  throw new Error(`Verification link not found (prefix: ${urlPrefix})`);
}

Prefer body_text for numeric OTP extraction — it's cleaner than parsing HTML.

Step 5 — Complete the Auth Flow

OTP flow:

const email = await waitForEmail(inbox.address, inbox.session_token, {
  subjectFilter: "Your verification code",
});
const otp = extractOTP(email);

await page.fill('[name="otp"]', otp);
await page.click('[type="submit"]');
await expect(page.locator('[data-testid="dashboard"]')).toBeVisible();

Verification link flow:

const link = extractVerificationLink(email, `${process.env.DEMO_BASE_URL}/verify`);
await page.goto(link);
await expect(page.locator("h1")).toHaveText("Account verified");

Full Working Example

// tests/auth/register.spec.ts
import { test, expect } from "@playwright/test";

const BASE = "https://uncorreotemporal.com/api/v1";
const API_HEADERS = {
  "Content-Type": "application/json",
  "X-API-Key": process.env.UCT_API_KEY!,
};

async function createInbox(ttlMinutes = 15) {
  const res = await fetch(`${BASE}/mailboxes`, {
    method: "POST",
    headers: API_HEADERS,
    body: JSON.stringify({ ttl_minutes: ttlMinutes }),
  });
  if (!res.ok) throw new Error(`createInbox failed: ${res.status}`);
  return res.json() as Promise<{ address: string; session_token: string }>;
}

async function waitForEmail(address: string, timeout = 30_000, subjectFilter?: string) {
  const encoded = encodeURIComponent(address);
  const deadline = Date.now() + timeout;
  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/mailboxes/${encoded}/messages`, { headers: API_HEADERS });
    if (!res.ok) { await sleep(2_000); continue; }
    const messages: Array<{ id: string; subject: string }> = await res.json();
    const hit = subjectFilter
      ? messages.find((m) => m.subject.toLowerCase().includes(subjectFilter.toLowerCase()))
      : messages[0];
    if (hit) {
      const full = await fetch(`${BASE}/mailboxes/${encoded}/messages/${hit.id}`, { headers: API_HEADERS });
      return full.json() as Promise<{ body_text: string | null; body_html: string | null }>;
    }
    await sleep(2_000);
  }
  throw new Error(`No email at ${address} after ${timeout}ms`);
}

async function deleteInbox(address: string) {
  const encoded = encodeURIComponent(address);
  await fetch(`${BASE}/mailboxes/${encoded}`, { method: "DELETE", headers: API_HEADERS });
}

function extractOTP(body_text: string | null, body_html: string | null): string {
  for (const content of [body_text, body_html]) {
    if (!content) continue;
    const m = content.match(/\b(\d{6})\b/);
    if (m) return m[1];
  }
  throw new Error("OTP not found in email");
}

function sleep(ms: number) { return new Promise<void>((r) => setTimeout(r, ms)); }

test("full signup -> OTP -> dashboard", async ({ page }) => {
  const inbox = await createInbox();
  try {
    await page.goto("/register");
    await page.fill('[name="email"]', inbox.address);
    await page.click('[type="submit"]');
    await page.waitForURL("**/confirm**");

    const email = await waitForEmail(inbox.address, 30_000, "OTP");
    const otp = extractOTP(email.body_text, email.body_html);

    await page.fill('[name="email"]', inbox.address);
    await page.fill('[name="otp"]', otp);
    await page.click('[type="submit"]');

    await expect(page.locator("h1")).toHaveText("Welcome to the dashboard");
  } finally {
    await deleteInbox(inbox.address);
  }
});

CI/CD Integration

# .github/workflows/e2e.yml
name: E2E Tests
on:
  push:
    branches: [main, staging]
  pull_request:

jobs:
  playwright:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    env:
      UCT_API_KEY: ${{ secrets.UCT_API_KEY }}
      DEMO_BASE_URL: ${{ vars.STAGING_URL }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: npm }
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx playwright test
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-report
          path: playwright-report/

Each CI run creates isolated inboxes. Parallel matrix jobs need zero coordination — each leg creates its own inbox.

Best Practices

Use subjectFilter when your app sends multiple emails per registration (welcome + confirmation). messages[0] on a two-message inbox is a race condition.

Distinguish network errors from missing emails. A 503 from the API should retry silently. An empty inbox after 30 seconds is a real failure.

Set ttl_minutes=5 in CI. Shorter TTLs reduce orphaned inbox accumulation if a test crashes before finally runs.

One inbox per test(), not per describe(). Two tests sharing an inbox re-introduce shared-state problems.

Add jitter for high-concurrency pipelines:

await sleep(Math.random() * 200);
const inbox = await createInbox();

Log the inbox address on failure:

test.info().annotations.push({ type: "inbox", description: inbox.address });

Why Real Email Testing Matters

Bug	Mock catches	Real inbox catches
`sendEmail()` not called	Yes	Yes
Email template render failure	No	Yes
Broken verification link format	No	Yes
Wrong base URL for the environment	No	Yes
SMTP credential expiry	No	Yes
OTP in email doesn't match backend	No	Yes

The most painful production bugs are in the second column. Testing against real SMTP delivery does not require standing up your own mail server. Programmable Temporary Email Infrastructure — what uncorreotemporal.com provides — is designed exactly for this.

Try It

The complete working examples — including the demo Express app the Playwright tests use as the application under test — are in the temporary-email-api-examples repository on GitHub.

Get your API key and start testing real email flows at https://uncorreotemporal.com

Why AI Agents in Google Colab Need Real Email Infrastructure

Francisco Perez — Mon, 23 Mar 2026 19:30:36 +0000

Capable but Incomplete

AI agents have made a remarkable leap in the past two years. They can write working code, call external APIs, browse the web, parse documents, orchestrate multi-step tasks, and operate in rich environments like Google Colab that give them access to real compute. By many measures, they look like fully capable automation systems.

But there is a class of workflow they consistently fail to complete: anything that requires interacting with email.

Not because the model is not smart enough. Not because the tooling is too complex. But because the infrastructure does not exist for them to use. Email — real email, with real SMTP, real delivery, real inboxes — has never been designed with agents in mind. And until it is, agents that seem capable of handling real-world tasks will keep running into the same invisible wall.

This is not a product gap. It is an infrastructure gap. That distinction matters more than most people realize.

The Illusion of Capability

Spend an hour with a capable agent in Google Colab and you will be impressed. It can install packages, generate and run code, query REST APIs, parse JSON, scrape pages, and feed results back into an LLM for reasoning. The loop feels tight and capable.

Then try to build an agent that registers for an external service and verifies the account.

The agent can fill out the form. It can submit the registration. It can handle the HTTP response. But then the service sends a confirmation email — and the agent has no inbox to receive it. The workflow terminates at the one point where email is a hard dependency, not an optional channel.

This is not an edge case. Account signup is one of the most common real-world automations. Password reset flows require email. OTP delivery relies on email. Subscription confirmations, trial activations, approval chains — nearly every SaaS product uses email as a critical control point at some stage of its workflow. An agent that cannot interact with email is an agent that can demo well but cannot complete real work.

The capability agents actually have is impressive. What is missing is the infrastructure layer that would let them use it.

Why Email Matters More Than It Seems

There is a tendency to treat email as a legacy communication channel — something old-fashioned that will eventually be replaced by APIs and webhooks. In practice, email is one of the most durable primitives on the internet.

It is the backbone of identity verification. You cannot register for a serious service without providing an email address that you control. That verification step is not a technical formality — it is a trust anchor. The email address is proof that you own an inbox, and owning an inbox is how the web has decided to define a real person — or a real entity — since the 1990s.

This means email is inherently tied to identity, authentication, and access control. It is the channel through which OTPs arrive, through which password resets are authorized, through which trial activations are gated. It is asynchronous by nature — the service sends a message and waits for you to act on it, without any guarantee of when you will respond. That async nature is exactly what makes it hard to handle programmatically.

Receiving email is not like calling an API. There is no request-response cycle you can initiate. You cannot await inbox.get(). An email arrives when the sender decides to send it, on infrastructure you do not control, and you need to be ready to receive it. For a human with an email client, this is trivial. For an agent, it requires infrastructure that does not come for free.

That infrastructure — real SMTP ingestion, programmatic inbox access, event-driven delivery — is not difficult to build. But it has not been built for agents. Most existing temporary email services were designed for humans who need a throwaway address in a browser. They are not designed to be called from Python, integrated into an agent loop, or managed programmatically. They are interfaces, not infrastructure.

The Current Broken Approaches

When developers hit this wall, they tend to reach for one of several workarounds. None of them hold up at scale.

Shared inboxes. Some teams use a real email account — Gmail, Outlook, a company address — as the target for all test emails. This works for one developer running one test at a time. The moment two CI workers run in parallel, messages from different runs land in the same inbox and cross-contaminate. There is no isolation. You cannot reliably know which message belongs to which run.

Mocks. You skip the real email flow and simulate it in your test. The agent pretends to receive an OTP. The test passes. What you have actually tested is your code's ability to handle a mocked input — not whether the real email delivery system works, not whether the OTP format matches what the actual service sends, not whether your regex correctly extracts from the real email body. Mocks are useful for unit testing logic. They are liabilities for integration testing real workflows.

Scraping Gmail. OAuth flows, scope management, token refresh, filtering out production emails from test emails — this is a non-trivial integration that has to be rebuilt for every new project. It requires a real account tied to a real identity. It creates noise in a production inbox. It is fragile to Gmail UI changes and quota limits. It is not composable into an agent framework.

Manual steps. The most honest broken approach: the human operator stops the agent, reads the email, copies the OTP, and resumes the workflow. This is not automation. This is automation with a gap that someone has to fill in by hand.

The reason these approaches persist is not that developers are unaware of their limitations. It is that there is no off-the-shelf infrastructure that solves the problem properly. So teams use what is available and work around the gaps.

Infrastructure vs Tooling

This distinction is the core of the problem.

A tool solves a specific, bounded task. "Read an email" is a tool. You reach for it when you need it, it does one thing, and you move on. A tool mindset works well when the surface is simple and the frequency is low. It does not scale.

Infrastructure is what you build when the tool is not enough. Infrastructure means:

Isolated inboxes: each agent session, each test run, each parallel worker gets its own inbox with no shared state
Lifecycle management: inboxes are created before they are needed, expire when they should, and are deleted when the workflow is done — without manual cleanup
Async handling: the system knows how to wait for an email to arrive without blocking the agent loop or polling in a tight loop
Programmatic access: every operation — create, read, delete — is available via an API that code can call, not a UI that a human clicks

The gap is not a missing feature. It is a missing layer. Consumer disposable email services were designed for humans. They solve the throwaway address problem for a person with a browser. The architectural intent was never to serve machines, so the design does not accommodate them: no authentication, no isolation, no API, no event delivery.

Building email as infrastructure — designed from the start for programmatic access by agents and automation systems — is a different project than adding an API to a browser tool. It requires a different mental model: the inbox is a resource, like a database row or a queue. It has an owner, a lifecycle, a quota, and an access control layer. Agents are first-class consumers of that resource, not afterthoughts.

This is where the category needs to go. Not "temporary email service" but "programmable email infrastructure." The difference is architectural, not cosmetic.

The Rise of MCP and Tool-Based Agents

The Model Context Protocol is changing how agents are built. Instead of hard-coding every capability into an agent framework, MCP standardizes how tools are defined, discovered, and called. An MCP-compatible agent can dynamically acquire new capabilities — search, code execution, database access, browser control — by connecting to MCP servers that expose those capabilities as typed tools.

The implication is significant: capabilities are becoming modular and externalized. Agent architectures are decoupling from specific implementations. A capability is a server you connect to, not code you write.

This is good for quality. When capabilities are externalized, they can be maintained by the teams with the deepest expertise in each domain. The team that builds the search tool knows more about search than the agent developer does. The team that builds the code execution environment knows more about sandboxing. This specialization produces better tools.

Email should follow the same pattern. If an agent needs email, it should be able to connect to an MCP server that exposes email as a typed, callable tool — without the agent developer needing to understand SMTP, Redis pub/sub, or inbox lifecycle management. The capability is available; the implementation is encapsulated.

When email is treated as a first-class tool in the MCP ecosystem, agent builders stop re-solving the infrastructure problem in every project. They connect to the server and get email. The work shifts to what actually matters: what the agent does with the email after it arrives.

What Real Email Infrastructure Looks Like

The characteristics are not exotic. They follow directly from what programmatic access requires.

Real SMTP ingestion. Not simulation. Not a service that pretends to accept email. A real mail transfer agent with real domain configuration, MX records, and compliance with RFC standards. Email that arrives is actual email — delivered via the same path as production traffic, subject to the same validation.

API-first access. Every operation is available as a documented HTTP endpoint. Creating an inbox is a POST. Reading messages is a GET. Deleting an inbox is a DELETE. The API is the interface; the UI is optional.

Ephemeral inboxes. Each inbox has a configurable TTL and expires deterministically. The agent does not need to worry about cleanup — the infrastructure handles it. Failure cases are covered automatically.

Isolation per task. Each agent session, each test run, each parallel workflow gets its own inbox. API key scoping ensures that one agent cannot accidentally read another's messages. There is no shared state to corrupt.

Event-driven delivery. When a message arrives, connected clients are notified immediately — no polling, no race conditions, no guessing at delivery latency. The agent opens a subscription before triggering the external workflow, then receives the event when the email arrives.

These are not aspirational features. They are the minimum viable set for infrastructure that agents can actually rely on.

What This Enables

When email works as infrastructure — not a workaround, not a mock — the scope of what agents can do expands considerably.

Autonomous account creation. An agent can register for external services, receive the confirmation email, extract the verification link, and complete the signup without any human in the loop. The entire flow, end-to-end.

Full CI/CD email testing. A test pipeline can provision a fresh inbox per job, trigger a real registration flow against a staging environment, receive the real email, verify the real OTP, and delete the inbox on completion. No shared inboxes, no mocks, no flaky tests caused by isolation failures.

AI agents completing real workflows. The category of task expands from "things that don't require email" to "anything that requires email" — which, in practice, means most of the real web. Signup flows, password resets, account verification, transactional approval chains, subscription activations.

Automation beyond APIs. Some systems do not have APIs. They have email. Legacy enterprise workflows, approval chains, notification systems built around email as the integration point. Agents that can interact with email can participate in these workflows without requiring modernization of the systems they interact with.

The unlock here is not incremental. It is categorical. Email is not one more tool in a long list. It is a gate that blocks access to a large fraction of the real web for agents that do not have it.

One Example of This Infrastructure

uncorreotemporal.com is a programmable temporary email infrastructure built around these principles. It runs a real SMTP server, stores messages with full RFC 2822 bytes alongside parsed fields, delivers events via WebSocket over Redis pub/sub, and exposes everything through a REST API and a native MCP server.

Inboxes are created per API call, scoped to API keys, and expire on configurable TTLs. The MCP server exposes five typed tools that agents can call without any email infrastructure knowledge. The whole thing can be used from Google Colab with a single pip install and an API key.

It is not the only way to solve the infrastructure problem. But it is an example of what the infrastructure layer looks like when it is built for agents rather than adapted from a browser tool.

The Agents That Will Matter

There is a useful frame for thinking about where agent capabilities are heading.

The first generation of capable agents impressed people because they could handle reasoning tasks: summarization, code generation, question answering. These are tasks that agents can complete entirely within their context window.

The second generation is defined by tool use. Agents that can call APIs, browse the web, execute code, and interact with external systems. Google Colab is a powerful environment for this — real Python, real compute, real libraries, real network access.

The third generation will be defined by infrastructure. Agents that do not just call tools, but participate in real-world systems as first-class actors. Systems that have state, history, async interactions, and long-lived workflows. Email is one of the first such systems.

Agents will not just call APIs. They will receive emails, respond to confirmation flows, participate in async approval chains, and interact with systems that were never designed with an API in mind. The infrastructure layer that makes this possible is not a feature request — it is the next constraint to solve.

Email is one of the first layers that needs to be solved properly. Not wrapped, not mocked, not scraped. Built as infrastructure, exposed as a tool, and made available to every agent that needs it.

The agents that will actually matter in production are the ones that can navigate the real web — including the parts that run on email.

uncorreotemporal.com

Add Email Capabilities to AI Agents in Google Colab

Francisco Perez — Sun, 22 Mar 2026 16:47:18 +0000

The Capability Gap

Modern AI agents have impressive reach. They can browse the web, execute code, call external APIs, read documents, and invoke dozens of tools. Frameworks like LangChain, CrewAI, and AutoGen ship with built-in tool wrappers for search engines, calculators, code interpreters, and databases.

But there is a capability they are almost universally missing: interacting with email.

This is not a minor gap. Email is the control plane for most external services. Account registration, one-time passwords, verification links, subscription confirmations, approval chains — nearly every system that matters uses email as a coordination mechanism. An agent that cannot interact with email can navigate to the "Check your inbox" page and stop there.

The usual workaround is to skip email entirely, mock the verification step, or require a human in the loop. These are all admissions of failure.

What agents actually need is email as a callable capability — not a workaround, not a one-off script, but a reusable component the agent can invoke whenever the task requires it.

From Script to Capability

There is a natural progression in how developers add email to their automation flows:

Stage 1 — One-off script. You write a quick function that creates an inbox, polls for a message, and extracts a code. It works. You ship it. Six weeks later a different agent needs email for a different flow, so you copy the function and modify it slightly. The codebase now has three slightly different implementations of the same thing. They diverge. One breaks.

Stage 2 — Shared utility. You extract the logic into a shared module. But it is still a flat collection of functions with no coherent interface. The caller needs to know which fields to pass, which headers to use, and how errors propagate. The abstraction is partial.

Stage 3 — Capability component. Email is encapsulated as a class with a clear interface. The agent does not know or care about HTTP calls, session tokens, or polling intervals. It calls create_inbox(), wait_for_email(), or extract_otp() — and gets back structured results. The implementation can be swapped or upgraded without touching the agent.

Stage 3 is what we want. Email becomes infrastructure that the agent consumes through a well-defined contract.

Designing the Interface

A minimal email capability interface for an agent needs to answer four questions:

Question	Operation
Where should I receive mail?	`create_inbox(ttl_minutes)`
Did any mail arrive?	`wait_for_email(address, timeout)`
What is the latest message?	`get_latest_message(address)`
What is the verification code?	`extract_otp(message)`

Let's define these contracts before writing any implementation:

# Contract: what the agent expects

def create_inbox(ttl_minutes: int = 10) -> Inbox:
    """
    Returns an Inbox with:
        .address  — e.g. mango-panda-42@uncorreotemporal.com
        .token    — session token for subsequent operations
        .expires_at — datetime string
    """

def wait_for_email(inbox: Inbox, timeout: int = 30) -> Message:
    """
    Blocks until an email arrives or timeout is reached.
    Returns a Message with:
        .id, .from_address, .subject, .body_text, .body_html
    Raises TimeoutError if no email arrives in time.
    """

def get_latest_message(inbox: Inbox) -> Message | None:
    """
    Returns the most recent message, or None if inbox is empty.
    Non-blocking.
    """

def extract_otp(message: Message, digits: int = 6) -> str:
    """
    Parses the message body for a numeric OTP code.
    Returns the code as a string.
    Raises ValueError if no code is found.
    """

Clean inputs, typed outputs, one job per function. The agent calls these without knowing anything about the underlying transport.

Building the EmailCapability Class

Here is a production-ready implementation against uncorreotemporal.com. This is the same class you would use in a Google Colab notebook, a pytest fixture, or a LangChain tool wrapper.

import re
import time
import requests
from dataclasses import dataclass

BASE_URL = "https://api.uncorreotemporal.com/api/v1"


@dataclass
class Inbox:
    address: str
    token: str
    expires_at: str


@dataclass
class Message:
    id: str
    from_address: str
    subject: str | None
    body_text: str | None
    body_html: str | None
    received_at: str
    is_read: bool


class EmailCapability:
    """
    Reusable email capability for AI agents.
    Wraps the uncorreotemporal.com API with a clean, agent-friendly interface.
    """

    def __init__(self, api_key: str | None = None):
        self._headers = (
            {"Authorization": f"Bearer {api_key}"} if api_key else {}
        )

    def create_inbox(self, ttl_minutes: int = 10) -> Inbox:
        """Create an ephemeral inbox. Returns address + session token."""
        resp = requests.post(
            f"{BASE_URL}/mailboxes",
            headers=self._headers,
            params={"ttl_minutes": ttl_minutes},
        )
        resp.raise_for_status()
        data = resp.json()
        return Inbox(
            address=data["address"],
            token=data.get("session_token", ""),
            expires_at=data["expires_at"],
        )

    def wait_for_email(
        self,
        inbox: Inbox,
        timeout: int = 30,
        poll_interval: float = 1.5,
    ) -> Message:
        """Block until a message arrives. Raises TimeoutError on timeout."""
        headers = self._auth_headers(inbox.token)
        deadline = time.time() + timeout

        while time.time() < deadline:
            resp = requests.get(
                f"{BASE_URL}/mailboxes/{inbox.address}/messages",
                headers=headers,
            )
            resp.raise_for_status()
            messages = resp.json()

            if messages:
                return self._fetch_message(inbox, messages[0]["id"])

            time.sleep(poll_interval)

        raise TimeoutError(
            f"No email received at {inbox.address} within {timeout}s"
        )

    def get_latest_message(self, inbox: Inbox) -> Message | None:
        """Non-blocking: return the most recent message, or None."""
        headers = self._auth_headers(inbox.token)
        resp = requests.get(
            f"{BASE_URL}/mailboxes/{inbox.address}/messages",
            headers=headers,
        )
        resp.raise_for_status()
        messages = resp.json()
        if not messages:
            return None
        return self._fetch_message(inbox, messages[0]["id"])

    def extract_otp(self, message: Message, digits: int = 6) -> str:
        """Extract a numeric OTP code from a message body."""
        body = message.body_text or ""
        pattern = rf"(?<!\d)(\d{{{digits}}})(?!\d)"
        match = re.search(pattern, body)
        if not match:
            raise ValueError(
                f"No {digits}-digit OTP found in message from {message.from_address}"
            )
        return match.group(1)

    def _auth_headers(self, session_token: str) -> dict:
        if self._headers:
            return self._headers
        return {"X-Session-Token": session_token}

    def _fetch_message(self, inbox: Inbox, message_id: str) -> Message:
        headers = self._auth_headers(inbox.token)
        resp = requests.get(
            f"{BASE_URL}/mailboxes/{inbox.address}/messages/{message_id}",
            headers=headers,
        )
        resp.raise_for_status()
        data = resp.json()
        return Message(
            id=data["id"],
            from_address=data["from_address"],
            subject=data.get("subject"),
            body_text=data.get("body_text"),
            body_html=data.get("body_html"),
            received_at=data["received_at"],
            is_read=data["is_read"],
        )

No additional dependencies — requests is pre-installed in every Colab runtime.

Using It in an Agent Loop

This is where the abstraction earns its value. Here is a simple agent loop running in Google Colab:

email = EmailCapability()  # anonymous mode; pass api_key= for higher quotas

# Step 1: Agent decides it needs an inbox
print("[agent] Task requires email. Creating inbox...")
inbox = email.create_inbox(ttl_minutes=10)
print(f"[agent] Inbox ready: {inbox.address}")

# Step 2: Agent performs the external action
def register_with_service(email_address: str) -> None:
    print(f"[agent] Registering at external service with: {email_address}")
    # requests.post("https://yourapp.com/signup", json={"email": email_address})

register_with_service(inbox.address)

# Step 3: Agent waits for the email capability to deliver the message
print("[agent] Waiting for verification email...")
try:
    message = email.wait_for_email(inbox, timeout=30)
    print(f"[agent] Email received from: {message.from_address}")
except TimeoutError:
    print("[agent] No email arrived. Aborting.")
    raise

# Step 4: Agent extracts the OTP and continues
otp = email.extract_otp(message)
print(f"[agent] OTP extracted: {otp}")
print("[agent] Task complete.")

The loop expresses intent: "I need to receive an email and extract a code." The capability handles the mechanism.

For flows requiring multiple emails:

first  = email.wait_for_email(inbox, timeout=30)   # confirmation email
second = email.wait_for_email(inbox, timeout=30)   # welcome email
receipt_link = re.search(r"https://\S+", second.body_text or "")

Before and After

Without the capability:

resp = requests.post("https://api.uncorreotemporal.com/api/v1/mailboxes", params={"ttl_minutes": 10})
data = resp.json()
address = data["address"]
token = data["session_token"]

deadline = time.time() + 30
found = None
while time.time() < deadline:
    r = requests.get(f"https://api.uncorreotemporal.com/api/v1/mailboxes/{address}/messages",
                     headers={"X-Session-Token": token})
    msgs = r.json()
    if msgs:
        full = requests.get(f"https://api.uncorreotemporal.com/api/v1/mailboxes/{address}/messages/{msgs[0]['id']}",
                            headers={"X-Session-Token": token})
        found = full.json()
        break
    time.sleep(1.5)

m = re.search(r"\b(\d{6})\b", found.get("body_text", ""))
otp = m.group(1)

With the capability:

inbox = email.create_inbox(ttl_minutes=10)
register_with_service(inbox.address)
message = email.wait_for_email(inbox, timeout=30)
otp = email.extract_otp(message)

Four lines. No duplication. Swappable at any layer.

The Natural Connection to MCP

Once you have a well-defined interface, the next step is exposing it as an MCP tool so any LLM agent can call it natively:

EmailCapability method	MCP Tool name
`create_inbox(ttl_minutes)`	`create_mailbox`
`wait_for_email(inbox, timeout)`	`get_messages(address)`
`get_latest_message(inbox)`	`get_messages(address, limit=1)`
read full body	`read_message(address, message_id)`

UnCorreoTemporal ships a native MCP server. Configure it once:

{
  "mcpServers": {
    "uncorreotemporal": {
      "command": "python",
      "args": ["-m", "uncorreotemporal.mcp.server"],
      "env": { "UCT_API_KEY": "uct_your_api_key_here" }
    }
  }
}

The model calls create_mailbox, get_messages, and read_message as first-class tool invocations — the same way it calls a web search or code interpreter.

Why This Architecture Supports It

Ephemeral inboxes by default. Each inbox carries an expires_at timestamp and is soft-deleted automatically. No teardown logic needed.

Structured message fields. The API returns body_text and body_html as pre-decoded Python strings. The internal core/parser.py handles RFC 2822 parsing, quoted-printable decoding, and base64 extraction.

Real SMTP delivery. Inboxes are not simulated — aiosmtpd in development, AWS SES in production. When wait_for_email returns, the message is there.

Async delivery events. The system publishes to Redis pub/sub (mailbox:{address}) the instant a message is stored. The WebSocket endpoint forwards these in milliseconds. wait_for_email can be upgraded from polling to push with no interface change.

Real Use Cases

Autonomous account provisioning — agent registers, confirms email, continues workflow
QA test suites — each test case gets an isolated inbox, parallel runs never collide
Onboarding automation — agent handles each transactional email at the right step
LLM research pipelines — model registers for service access, processes confirmation, cleans up

The agent loop is always the same: create inbox, perform action, wait for email, extract signal, continue.

Conclusion

The missing piece in most agent capability stacks is not a new model feature — it is a clean abstraction over infrastructure that has existed for decades.

Email is not a niche integration. It is a coordination primitive that most real systems depend on. Building agents that treat it as a first-class capability — rather than bolting on one-off scripts that break and diverge — is the difference between fragile prototypes and systems that hold up.

The EmailCapability class above is a starting point. The interface is small by design. It composes cleanly with agent loops, pytest fixtures, LangChain tools, and MCP servers.

Try it at uncorreotemporal.com — your first inbox is one requests.post() away.

Automate OTP Flows in Google Colab with AI Agents

Francisco Perez — Sat, 21 Mar 2026 21:26:39 +0000

You're automating a signup flow. Everything is scripted — the form fill, the button click, the redirect. Then you hit a wall: an OTP arrives in an email, and your script stops cold.

Someone has to open a browser, read the code, and type it in. Or worse, you've built a brittle parser that breaks every time the email template changes. Or you're sharing a test inbox with five other engineers and can't tell which OTP is yours.

This is one of those problems that sounds simple and isn't. Let me show you a pattern that solves it cleanly.

Why Automating OTP Extraction Is Harder Than It Looks

The core issue is that email is asynchronous. You don't know when the message will arrive. You can't just time.sleep(5) and hope for the best — delivery can take anywhere from half a second to thirty seconds depending on the service, load, and your location.

Beyond timing, there's the parsing problem. OTP emails come in HTML. The six-digit code might be inside a <td>, wrapped in a <strong>, styled with inline CSS, and surrounded by marketing copy. Writing a regex against raw HTML is fragile and will break the moment the vendor's design team touches the template.

And then there's the shared inbox problem. If you're running parallel tests, multiple OTP emails land in the same inbox. You need to know which one belongs to which test run. Most setups don't have a clean answer to this.

A proper solution needs:

Isolated inboxes per test run — no cross-contamination
Reliable polling — wait until the email arrives, up to a configurable timeout
Plain-text access — skip the HTML parser entirely

The Pattern: Create, Wait, Extract

The approach is straightforward:

Create a fresh inbox before each flow
Register (or sign up) using that inbox's address
Poll until the OTP email arrives
Extract the code from the plain-text body

This is a pattern, not a hack. It works in pytest fixtures, Playwright scripts, n8n flows, LangChain agents, and raw Python scripts. The inbox is ephemeral — it gets created for the test and expires automatically.

uncorreotemporal.com provides this infrastructure: a real SMTP backend, isolated inboxes via REST API, and per-inbox session tokens so each test runs independently.

Full Example: OTP Extraction in Python

This is a complete, copy-paste example. No mocks, no shared state.

import requests
import re
import time

BASE_URL = "https://api.uncorreotemporal.com"

def create_inbox(ttl_minutes: int = 10) -> tuple[str, str]:
    """Create a temporary inbox. Returns (address, session_token)."""
    resp = requests.post(
        f"{BASE_URL}/api/v1/mailboxes",
        params={"ttl_minutes": ttl_minutes}
    )
    resp.raise_for_status()
    data = resp.json()
    return data["address"], data["session_token"]

def wait_for_email(
    address: str,
    session_token: str,
    timeout: int = 60,
    poll_interval: int = 3
) -> dict:
    """Poll until at least one email arrives. Raises TimeoutError if none."""
    headers = {"Session-Token": session_token}
    deadline = time.monotonic() + timeout

    while time.monotonic() < deadline:
        resp = requests.get(
            f"{BASE_URL}/api/v1/mailboxes/{address}/messages",
            headers=headers
        )
        resp.raise_for_status()
        messages = resp.json()

        if messages:
            return messages[0]  # most recent first

        time.sleep(poll_interval)

    raise TimeoutError(f"No email received within {timeout}s at {address}")

def get_message_body(
    address: str,
    message_id: str,
    session_token: str
) -> str:
    """Fetch the full message and return the plain-text body."""
    headers = {"Session-Token": session_token}
    resp = requests.get(
        f"{BASE_URL}/api/v1/mailboxes/{address}/messages/{message_id}",
        headers=headers
    )
    resp.raise_for_status()
    data = resp.json()
    return data.get("body_text") or ""

def extract_otp(text: str, pattern: str = r'\b\d{6}\b') -> str | None:
    """Extract the first OTP match from text."""
    matches = re.findall(pattern, text)
    return matches[0] if matches else None

# -------------------------------------------------------
# Main flow
# -------------------------------------------------------
address, session_token = create_inbox(ttl_minutes=10)
print(f"[+] Inbox: {address}")

# Use this address in your actual signup/login flow
# e.g. playwright.fill("#email", address)
# e.g. requests.post("https://app.example.com/register", json={"email": address})
print(f"[*] Submitting signup with {address}...")

# Wait for the OTP email
try:
    summary = wait_for_email(address, session_token, timeout=60)
    print(f"[+] Email arrived: '{summary['subject']}'")
except TimeoutError as e:
    print(f"[-] {e}")
    raise

# Fetch full body and extract OTP
body = get_message_body(address, summary["id"], session_token)
otp = extract_otp(body)

if otp:
    print(f"[+] OTP: {otp}")
else:
    print("[-] OTP not found in message body")
    print(f"    Body preview: {body[:200]}")

The session_token is scoped to the inbox — it can only read messages from that specific address. Each test gets its own token, so parallel runs are fully isolated.

Handling Edge Cases

Timeout and retries

The 60-second default covers most services. For slower flows, increase it:

summary = wait_for_email(address, session_token, timeout=120)

If you want exponential backoff instead of fixed polling:

def wait_for_email_backoff(address, session_token, timeout=60):
    deadline = time.monotonic() + timeout
    interval = 2

    while time.monotonic() < deadline:
        resp = requests.get(
            f"{BASE_URL}/api/v1/mailboxes/{address}/messages",
            headers={"Session-Token": session_token}
        )
        messages = resp.json()
        if messages:
            return messages[0]
        interval = min(interval * 1.5, 15)
        time.sleep(interval)

    raise TimeoutError(f"Timeout at {address}")

Multiple emails in the inbox

Filter by subject when the flow sends more than one email:

otp_email = next(
    (m for m in messages if "verification" in (m["subject"] or "").lower()),
    None
)

OTP pattern variations

# 4-digit PIN
extract_otp(body, pattern=r'\b\d{4}\b')

# 8-digit code
extract_otp(body, pattern=r'\b\d{8}\b')

# UUID-style token
extract_otp(body, pattern=r'[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}')

HTML-only emails

import html, re

def strip_html(html_body: str) -> str:
    text = re.sub(r'<[^>]+>', ' ', html_body)
    return html.unescape(text)

body = data.get("body_text") or strip_html(data.get("body_html") or "")

Using This in Google Colab

Colab is useful for quick experiments: no local setup, shareable notebooks, free compute. The code above runs as-is in a Colab cell. For AI agent workflows — LangChain, CrewAI, or raw function-calling — the inbox creation and OTP extraction functions map directly to tool definitions. An agent can call create_inbox(), hand the address to a browser automation step, then call wait_for_email() and extract_otp() to complete the verification without human intervention.

The uncorreotemporal.com MCP server exposes the same capabilities as structured tools, so Claude Desktop and any MCP-compatible agent can call them natively without writing a single line of HTTP code.

Why This Works Reliably

Real SMTP, not mocks. The inbox receives email over actual SMTP from real sending services. No simulation layer that might behave differently from production.

Isolated inboxes. Each call to POST /api/v1/mailboxes creates a new address. Messages are only accessible via the inbox's session_token. Parallel test runs cannot interfere.

Async delivery handled by the API. The polling loop is simple because the backend handles the async complexity — SES inbound webhook, message storage, indexed delivery time. You're polling a fast read query, not an external SMTP server.

Real Use Cases

CI/CD pipelines: Register a test account, verify the email, run authenticated tests, expire the inbox. Fully automated, zero manual steps.
Automated QA: Playwright or Selenium tests that complete full registration flows including email verification.
Account creation bots: Bulk testing of onboarding flows across multiple accounts in parallel, each with its own isolated inbox.
AI agents: Agents that complete multi-step signup flows autonomously — create inbox, fill form, extract OTP, submit verification, proceed.

Get Started

The API requires no upfront setup for anonymous inboxes — just POST to create one and start receiving email. Free tier covers development and small test suites.

Try it now at uncorreotemporal.com. The full API reference is in the docs, and the MCP server config is available for agent workflows in Claude Desktop or any MCP-compatible client.

OTP extraction doesn't have to be the flaky, manual step that breaks your automation. With isolated inboxes and a clean polling loop, it's just another function call.

Using Google Colab MCP with a Temporary Email API

Francisco Perez — Fri, 20 Mar 2026 16:42:52 +0000

The Gap in the MCP Tool Ecosystem

The Model Context Protocol is doing something important: it is turning external capabilities into first-class tools that AI agents can discover and invoke without custom integration code. Google Colab MCP takes this further — your agent can now execute Python code in a real Colab runtime as a tool call. Search, web browsing, code execution, structured data retrieval: these are all becoming standardized tool surfaces.

But there is a gap that almost every real-world automation workflow hits eventually.

Agents still cannot reliably interact with email.

This is not an oversight. Email is structurally awkward to expose as a tool. It requires live SMTP infrastructure, async delivery timing, MIME parsing, and some mechanism to match a received message to a specific agent session. None of that is obvious to implement, and existing solutions — shared inboxes, Gmail IMAP, mocked flows — break under real conditions.

This article shows how to close that gap. You will see how a temporary email API exposes real inbox capabilities as MCP tools, how to call those tools from Google Colab using the Python MCP client, and why the MCP approach is meaningfully different from calling the REST API directly.

What MCP Actually Changes

The difference between calling a REST API and using an MCP tool is not just syntax. It is a change in who is responsible for knowing what is available.

With a REST API, the agent (or the human building the agent) has to know the endpoint, the method, the request shape, and the response schema before writing a single line of code. The knowledge is baked into the integration layer — usually as custom glue code, a wrapper function, or a prompt that tells the LLM what to call.

With MCP, the agent calls tools/list and gets back a structured description of every available capability: names, descriptions, input schemas, and output shapes. The agent can reason about which tools to use without any prior instruction. An agent runtime like Claude Desktop, AutoGen, or LangGraph can consume an MCP server it has never seen before and immediately know what it can do.

This matters for agent design in a concrete way: it removes the coupling between the agent's reasoning and the specific API surface of each service. You do not need to update your prompt or your wrapper code when the underlying service changes. You add a server to the configuration, and the capability becomes available.

For email specifically, this means the agent does not need to know anything about SMTP, MIME, or polling intervals. It calls create_signup_inbox, gets an address, uses it, and calls wait_for_verification_email. The infrastructure knowledge stays in the server.

The Missing Tool: Email

Email shows up as a dependency in a surprisingly large fraction of real-world automation:

Account signups that require a confirmation link before the account activates
Two-factor authentication flows where the second factor is an OTP sent to the registered address
Subscription confirmations that gate access to an API key or resource
Password resets that block account recovery until the user clicks a link

Each of these is a hard stop for an autonomous agent. The agent can complete every other step of the workflow. Then it hits "check your email" and either stalls waiting for human input or fails entirely.

The workarounds that teams reach for do not hold up under scrutiny:

Shared inboxes (qa-team@company.com) introduce race conditions immediately. Ten parallel test runs create ten verification emails into one inbox. There is no clean way to correlate which code belongs to which session.

Gmail IMAP requires OAuth2 credentials, refresh token logic, and ongoing credential management. App passwords get blocked by workspace policies. IMAP polling adds unpredictable latency. And you are parsing raw RFC 2822 MIME with all its multipart structure on your end — it breaks every few months.

Mocking the email step means your agent never exercises the real flow. When you need the agent to interact with a third-party service that controls its own email delivery, there is nothing to mock.

Manual intervention defeats the purpose. An agent that pauses for a human to check an inbox is not automating the flow; it is just moving the manual step around.

What agents actually need is a programmable inbox: created on demand, accepting real SMTP traffic, queryable via a structured interface, and gone when the job is done.

The MCP Email Tools

UnCorreoTemporal exposes exactly this infrastructure as an MCP server. The server runs over streamable-HTTP at https://uncorreotemporal.com/mcp and authenticates callers with a Bearer token (Authorization: Bearer uct_your_key_here).

It exposes six tools. Here they are with their actual input schemas, taken directly from the server implementation:

create_signup_inbox

Input:  service_name (str), ttl_minutes (int, optional)
Output: {inbox_id, email, expires_at, service_name}

Creates a live temporary inbox. The email field is the SMTP address — human-readable, like coral-tiger-17@uncorreotemporal.com. The inbox is live immediately and expires automatically at expires_at.

wait_for_verification_email

Input:  inbox_id (str), timeout_seconds (int=90), poll_interval_seconds (int=3),
        subject_contains (str, optional), from_contains (str, optional)
Output: {message_id, status, ...} or {status: "timeout"}

Blocks until a matching email arrives or the timeout is exceeded. The subject_contains and from_contains filters let you wait for a specific sender or subject line without reading everything.

get_latest_email

Input:  inbox_id (str), mark_as_read (bool=False)
Output: full message object with body_text, body_html, from_address, subject, received_at

Retrieves the most recent message in the inbox, with full body content. The server handles MIME parsing — body_text and body_html are already decoded strings.

extract_otp_code

Input:  message_text (str, optional), inbox_id (str, optional), message_id (str, optional),
        otp_length_min (int=4), otp_length_max (int=8)
Output: {otp_code, candidates}

Extracts a numeric OTP from message text. You can pass message_text directly or let the tool fetch the message itself via inbox_id + message_id.

extract_verification_link

Input:  message_text (str, optional), inbox_id (str, optional), message_id (str, optional),
        preferred_domains (list[str], optional)
Output: {verification_link, candidates}

Extracts the most likely verification URL from message text. Use preferred_domains to bias toward a specific service's domain when multiple links are present.

complete_signup_flow

Input:  service_name (str), timeout_seconds (int=90), ttl_minutes (int, optional),
        subject_contains (str, optional), from_contains (str, optional),
        preferred_domains (list[str], optional)
Output: {status, email, verification_link, otp_code, verification_message, ...}

An end-to-end composite tool: creates the inbox, waits for the email, extracts both the verification link and the OTP in a single call. Returns status: "success" when at least one of the two was found, status: "partial_success" if the email arrived but neither could be extracted, or status: "timeout" if nothing came through.

This is the key tool for agents. Instead of orchestrating five separate calls, the agent calls one tool and gets back everything it needs to complete a verification flow.

Using Email as a Tool in Colab

Google Colab gives you a Python runtime that is already connected to the internet and has pip available. The mcp Python package supports streamable-HTTP transport, which means you can connect to the UnCorreoTemporal MCP server directly from a Colab cell.

Install the client:

# Cell 1
!pip install mcp httpx -q

Connect to the server:

# Cell 2
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

UCT_API_KEY = "uct_your_key_here"  # get one at uncorreotemporal.com
MCP_URL = "https://uncorreotemporal.com/mcp"

async def list_tools():
    async with streamablehttp_client(
        url=MCP_URL,
        headers={"Authorization": f"Bearer {UCT_API_KEY}"}
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            return [t.name for t in tools.tools]

tools = asyncio.run(list_tools())
print(tools)
# ['create_signup_inbox', 'wait_for_verification_email', 'get_latest_email',
#  'extract_otp_code', 'extract_verification_link', 'complete_signup_flow']

The agent discovers what is available without any hardcoded knowledge. Now use the composite tool:

# Cell 3 — create an inbox ready for a signup flow
import json

async def create_inbox(service_name: str):
    async with streamablehttp_client(
        url=MCP_URL,
        headers={"Authorization": f"Bearer {UCT_API_KEY}"}
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool(
                "create_signup_inbox",
                {"service_name": service_name, "ttl_minutes": 15}
            )
            return json.loads(result.content[0].text)

inbox = asyncio.run(create_inbox("GitHub"))
print(f"Inbox address: {inbox['email']}")
print(f"Expires at:    {inbox['expires_at']}")
# Inbox address: coral-tiger-17@uncorreotemporal.com
# Expires at:    2026-03-20T10:45:00Z

Use the address to register with the target service, then retrieve everything in one call:

# Cell 4 — after triggering the signup email, call complete_signup_flow

async def run_complete_flow(service_name: str):
    async with streamablehttp_client(
        url=MCP_URL,
        headers={"Authorization": f"Bearer {UCT_API_KEY}"}
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # One call: creates inbox, waits for email, extracts link + OTP
            result = await session.call_tool(
                "complete_signup_flow",
                {
                    "service_name": "GitHub",
                    "timeout_seconds": 90,
                    "ttl_minutes": 15,
                }
            )
            return json.loads(result.content[0].text)

flow = asyncio.run(run_complete_flow("GitHub"))
print(f"Status:  {flow['status']}")
print(f"Email:   {flow['email']}")
print(f"Link:    {flow['verification_link']}")
print(f"OTP:     {flow['otp_code']}")
# Status:  success
# Email:   coral-tiger-17@uncorreotemporal.com
# Link:    https://github.com/users/confirm-email?token=eyJh...
# OTP:     None  (GitHub uses links, not OTPs)

The complete_signup_flow tool returns both verification_link and otp_code — the caller does not need to know which one the service uses. If it is an OTP-based service, otp_code will be populated. If it sends a link, verification_link will be populated. The agent handles whichever is non-null.

MCP vs REST: The Design Difference

Here is the same flow written against the REST API directly:

# REST approach
import requests, re, time

BASE = "https://uncorreotemporal.com/api/v1"
HEADERS = {"Authorization": "Bearer uct_your_key_here"}

# Step 1: create inbox
resp = requests.post(f"{BASE}/mailboxes", params={"ttl_minutes": 15}, headers=HEADERS)
data = resp.json()
address = data["address"]
session_token = data["session_token"]

# Step 2: poll for messages (manual loop)
msg_headers = {"X-Session-Token": session_token}
deadline = time.time() + 90
message = None

while time.time() < deadline:
    msgs = requests.get(
        f"{BASE}/mailboxes/{address}/messages",
        headers=msg_headers
    ).json()
    if msgs:
        full = requests.get(
            f"{BASE}/mailboxes/{address}/messages/{msgs[0]['id']}",
            headers=msg_headers
        ).json()
        message = full
        break
    time.sleep(3)

# Step 3: extract link manually
if message:
    match = re.search(r"https?://[^\s]+verify[^\s]+", message["body_text"])
    link = match.group(0) if match else None

This works, and it is what a Colab notebook using raw requests looks like. But notice what the developer had to build:

A polling loop with timeout management
Session token tracking per inbox
Manual regex extraction for links and OTPs
Knowledge of the API endpoint structure

Compare to the MCP approach:

# MCP approach — same outcome, zero glue code
result = await session.call_tool(
    "complete_signup_flow",
    {"service_name": "GitHub", "timeout_seconds": 90, "ttl_minutes": 15}
)
flow = json.loads(result.content[0].text)
link = flow["verification_link"]

The MCP approach is not just shorter. It is structurally different in a way that matters at scale:

	REST	MCP
Tool discovery	Manual (docs, prompts)	Automatic (tools/list)
Polling	Developer implements	Server implements
Extraction logic	Developer implements regex	Tool handles OTP + link extraction
Session management	Developer tracks tokens	Server manages per-call auth
Composability	One-off integration	Reusable across all MCP runtimes
Agent integration	Custom per-framework	Standard across Claude, AutoGen, LangGraph

The REST API is the right choice when you are building a custom pipeline where you control every step. MCP is the right choice when the consumer is an agent that needs to reason about what it can do and orchestrate the steps dynamically.

Architecture: What Makes This Work

The tools describe what agents can do. The architecture explains why they are reliable.

When any service sends a verification email to a UnCorreoTemporal address, here is what happens:

External sender → AWS SES (spam/virus filtering)
                         ↓ SNS webhook
              POST /api/v1/ses/inbound
                         ↓
              core/delivery.deliver_raw_email()
               ┌──────────┴──────────┐
               ↓                     ↓
         PostgreSQL             Redis pub/sub
         (message stored)    (channel: mailbox:{address})
                                      ↓
                             WebSocket push to browser
                             /ws/inbox/{address}

Key properties:

Real SMTP delivery. In production, emails travel through AWS SES. There is no simulation, no test mode — any sender on the internet can deliver to a UnCorreoTemporal address, and it works. The wait_for_verification_email tool is waiting for messages that actually arrived via SMTP, not mocked locally.

Parsed at ingest. deliver_raw_email() parses the RFC 2822 message, extracts body_text and body_html, stores everything in PostgreSQL. By the time a tool call reads the message, the raw MIME has already been processed. The agent gets clean strings.

Ephemeral by design. Every inbox has an expires_at timestamp. A background worker soft-deletes expired mailboxes automatically. The agent creates an inbox, uses it, and never needs to clean up — it just stops calling it.

Parallel-safe. Each inbox is isolated. 50 parallel agent sessions creating 50 inboxes never share state. There are no race conditions on the inbox side.

The MCP server itself is stateless per request. Each tool call creates its own database connection, performs the operation, and closes. The server holds no inbox state between calls — everything lives in PostgreSQL.

Why This Matters for Autonomous Agents

The steady-state for AI agents is increasing autonomy over longer-horizon tasks. An agent that can write code, search the web, call APIs, and execute logic in Colab is already impressive. But it hits a ceiling the moment it needs to interact with a service that uses email as a control point.

That ceiling is structural, not technical. The agent is not missing intelligence — it is missing infrastructure. Give it a programmable inbox as a tool, and the ceiling disappears:

Autonomous account provisioning: The agent registers on external services, confirms the email, continues the workflow — no human in the loop.
CI/CD email testing: Every build creates fresh inboxes, triggers signup flows against the production login system, asserts verification emails arrived, tears down automatically.
Parallel agent runs: 20 sessions, 20 inboxes, zero shared state. Each agent operates in complete isolation.
Research workflows: An agent registers for access to a dataset, receives and processes the confirmation, downloads the resource, and the inbox expires when the job is done.

The common thread is that email is not optional in these flows. It is the coordination mechanism that external services use to verify identity and gate access. Agents that cannot handle it are excluded from a large class of real-world tasks.

The MCP interface makes this accessible without infrastructure overhead. You point your agent at the server, it discovers the tools, and email becomes a capability — not a special case.

Conclusion

Google Colab MCP and similar execution environments are expanding what agents can do. But code execution is only one piece of real-world automation. Email is another, and it has been the missing piece for longer than it should have been.

The UnCorreoTemporal MCP server gives agents six tools for handling email flows: create an inbox, wait for a message, read its content, extract an OTP, extract a verification link, or do all of it in one call with complete_signup_flow. The server runs over streamable-HTTP and works with any MCP-compatible runtime — including a Colab cell with the mcp Python library installed.

The infrastructure is real: SMTP delivery via AWS SES, PostgreSQL-backed message storage, Redis pub/sub for real-time events, ephemeral inboxes that expire automatically. There is no simulation. The emails that arrive are emails that actually traveled across the internet.

If you are building agents that need to interact with real-world services, the inbox is one call_tool away. Start at uncorreotemporal.com.

Give Your AI Agent a Real Email Inbox in Google Colab

Francisco Perez — Thu, 19 Mar 2026 19:13:17 +0000

The Gap Nobody Talks About

You can run a Python agent in Google Colab. It can call APIs, write code, scrape pages, parse documents, and call LLMs. But the moment that agent needs to complete a real-world account registration — the kind that sends a verification email — it stops cold.

No inbox. No way to receive an OTP. The flow is blocked.

This is not a minor inconvenience. A large fraction of real-world automation depends on email as a control point:

Account signups with email confirmation
Two-factor authentication via OTP
Subscription confirmations and approval flows
Password resets and verification links

The agent can get to the "Check your email" page. It just can't do anything after that.

This article shows how to fix that. You'll have a working, programmable email inbox running in Google Colab by the end — one the agent controls entirely, no human in the loop.

Why Traditional Solutions Fail

The obvious workarounds don't hold up in practice.

Mocking the email step is the most common approach. You bypass the verification entirely in your test environment. The problem: the agent doesn't learn to handle the real flow, and when you need production-level automation (provisioning accounts on external services, for example), the mock is useless.

Using a shared inbox like qa-team@yourdomain.com introduces race conditions the moment anything runs in parallel. Two agent runs trigger two verification emails into the same inbox. You can't reliably match which code belongs to which session.

Gmail IMAP is fragile at a level that makes it unsuitable for automated use. OAuth2 tokens expire, app passwords get blocked by workspace policies, IMAP polling adds unpredictable latency, and you're parsing raw RFC 2822 MIME messages — base64-encoded, quoted-printable — to get to the text body. It breaks every few months.

Manual verification defeats the purpose. Agents that pause for human input are not agents; they're wizards.

What Agents Actually Need

An agent that can handle email needs four things:

An email address it controls, created on demand
Real SMTP delivery — not simulated, not mocked
A programmatic way to read incoming messages
Automatic cleanup when the session ends

This maps exactly to what a programmable temporary email infrastructure provides.

UnCorreoTemporal is that infrastructure. It accepts real SMTP traffic, stores messages in a PostgreSQL database, exposes a REST API for reading them, and pushes real-time events via WebSockets. Every inbox is ephemeral by design — it expires on a configurable schedule without any teardown code required.

It is also MCP-native, which means Claude Desktop and any other MCP-compatible agent runtime can call it as a tool directly. More on that at the end.

Setting Up in Google Colab

Open a new Colab notebook. No special setup required — requests is available in every Colab runtime.

# Cell 1 — install nothing, requests is pre-installed
import requests
import re
import time

BASE_URL = "https://api.uncorreotemporal.com/api/v1"

Create an Inbox

A single POST call creates an ephemeral inbox. No authentication required for anonymous use. The response includes the address and a session_token that authenticates all subsequent operations.

# Cell 2 — create inbox
def create_inbox(ttl_minutes: int = 10) -> tuple[str, str]:
    resp = requests.post(
        f"{BASE_URL}/mailboxes",
        params={"ttl_minutes": ttl_minutes},
    )
    resp.raise_for_status()
    data = resp.json()
    return data["address"], data["session_token"]

address, token = create_inbox(ttl_minutes=10)
print(f"Inbox: {address}")
# Output: mango-panda-42@uncorreotemporal.com

The address is human-readable (adjective-noun-number@uncorreotemporal.com) and unique per creation. The inbox is live immediately — it starts accepting SMTP delivery the moment it's created.

Read Incoming Messages

The list endpoint returns message metadata without loading full bodies, keeping responses fast. Fetch the full body only when a message has arrived.

# Cell 3 — wait for incoming email
def wait_for_email(address: str, token: str, timeout: int = 30) -> dict:
    headers = {"X-Session-Token": token}
    deadline = time.time() + timeout

    while time.time() < deadline:
        resp = requests.get(
            f"{BASE_URL}/mailboxes/{address}/messages",
            headers=headers,
        )
        resp.raise_for_status()
        messages = resp.json()

        if messages:
            msg_id = messages[0]["id"]
            full = requests.get(
                f"{BASE_URL}/mailboxes/{address}/messages/{msg_id}",
                headers=headers,
            )
            full.raise_for_status()
            return full.json()

        time.sleep(1.5)

    raise TimeoutError(f"No email received within {timeout}s")

The full message response includes body_text and body_html as pre-decoded Python strings. No MIME parsing on your end — the server handles all of that internally via core/parser.py.

End-to-End Example: OTP Automation in Colab

Here's a complete flow you can run cell by cell. It simulates a signup that triggers a verification email, waits for it, and extracts the OTP.

# Cell 4 — simulate a service that sends a verification email
def simulate_signup(email: str) -> None:
    """
    In a real scenario this would be:
        requests.post("https://yourservice.com/register", json={"email": email})
    """
    print(f"[→] Registering with email: {email}")

# Cell 5 — extract OTP from body text
def extract_otp(body_text: str) -> str:
    match = re.search(r"(?<!d)(d{6})(?!d)", body_text)
    if not match:
        raise ValueError("No 6-digit OTP found in email body")
    return match.group(1)

# Cell 6 — full end-to-end flow
import requests, re, time

BASE_URL = "https://api.uncorreotemporal.com/api/v1"

# Step 1: create inbox
resp = requests.post(f"{BASE_URL}/mailboxes", params={"ttl_minutes": 10})
resp.raise_for_status()
data = resp.json()
address, token = data["address"], data["session_token"]
print(f"[✓] Inbox created: {address}")
print(f"[✓] Expires at: {data['expires_at']}")

# Step 2: use the address to sign up (replace with your service)
print(f"[→] Submitting signup with {address}...")
# requests.post("https://yourservice.com/register", json={"email": address})

# Step 3: wait for the verification email
print("[…] Waiting for verification email...")
headers = {"X-Session-Token": token}
deadline = time.time() + 30

message = None
while time.time() < deadline:
    resp = requests.get(
        f"{BASE_URL}/mailboxes/{address}/messages",
        headers=headers,
    )
    resp.raise_for_status()
    msgs = resp.json()
    if msgs:
        msg_id = msgs[0]["id"]
        full = requests.get(
            f"{BASE_URL}/mailboxes/{address}/messages/{msg_id}",
            headers=headers,
        )
        full.raise_for_status()
        message = full.json()
        break
    time.sleep(1.5)

if not message:
    raise TimeoutError("Email not received in 30 seconds")

print(f"[✓] Email received from: {message['from_address']}")
print(f"[✓] Subject: {message['subject']}")

# Step 4: extract OTP
body = message["body_text"] or ""
match = re.search(r"(?<!d)(d{6})(?!d)", body)
if match:
    otp = match.group(1)
    print(f"[✓] OTP extracted: {otp}")
else:
    print("[!] No OTP found — check body_html if service sends HTML-only email")
    print(message["body_html"][:500])

print("[✓] Flow complete")

Real-Time Option: WebSocket Instead of Polling

import asyncio
import json
import websockets

async def wait_for_email_ws(address: str, token: str) -> str:
    url = f"wss://api.uncorreotemporal.com/ws/inbox/{address}?token={token}"
    async with websockets.connect(url) as ws:
        async for raw in ws:
            event = json.loads(raw)
            if event.get("event") == "new_message":
                return event["message_id"]

The event is {"event": "new_message", "message_id": "<uuid>"}. The server sends a keepalive ping every 30 seconds to prevent connection drops in long-running workflows.

How This Works Internally

External SMTP sender
        │
        ▼
AWS SES (spam + virus filter)
        │ SNS webhook
        ▼
POST /api/v1/ses/inbound
        │
        ▼
core/delivery.deliver_raw_email()
        │
   ┌────┴────┐
   ▼         ▼
PostgreSQL  Redis pub/sub
(messages)  channel: mailbox:{address}
                │
                ▼
        WebSocket /ws/inbox/{address}
        {"event": "new_message", "message_id": "..."}

Key components:

FastAPI async backend: All API endpoints use async SQLAlchemy with PostgreSQL. The ORM models define body_text, body_html, from_address, subject, and attachments as top-level fields — no raw MIME on your side.
SMTP ingestion: A local aiosmtpd-based server handles direct SMTP delivery in development. In production, AWS SES receives inbound mail and forwards it via SNS webhook to /api/v1/ses/inbound. Both paths funnel through the same deliver_raw_email() function.
Redis pub/sub: When a message is stored, it publishes to mailbox:{address}. The WebSocket handler in ws/inbox.py subscribes to that channel and forwards the event to connected clients.
Background expiration: Inboxes carry an expires_at timestamp. A background worker soft-deletes expired mailboxes automatically. No cleanup code in your automation.

Why This Matters for AI Agents

Email is a coordination primitive. It's how external services signal back to your agent. Without it:

Agents can't complete onboarding flows on third-party platforms
QA pipelines that test registration flows require human testers
Multi-step automation that depends on email confirmations stalls indefinitely

Concrete use cases this enables:

Autonomous signup testing: Create an account, confirm the email, assert the welcome message arrived — fully automated, repeatable in CI
Agent-driven account provisioning: An agent registers on a third-party service, receives and processes the confirmation, continues the workflow
Parallel testing without collision: 20 test runs, 20 inboxes, zero shared state
Ephemeral research agents: An agent registers for access to a dataset or service, uses it, and the inbox expires when the job is done

MCP Integration for Claude and Compatible Agents

{
  "mcpServers": {
    "uncorreotemporal": {
      "command": "python",
      "args": ["-m", "uncorreotemporal.mcp.server"],
      "env": { "UCT_API_KEY": "uct_your_key_here" }
    }
  }
}

The agent can then call create_mailbox(), get_messages(address), and read_message(address, message_id) as first-class tools.

What You Can Build

The pattern shown here — create inbox, trigger external flow, wait for email, extract code or link — composes into larger systems:

A pytest fixture that creates a fresh inbox per test case and tears down automatically
A CI/CD stage that provisions test accounts on every build with zero shared credentials
A Colab-based agent that navigates real-world signup flows end to end
A research tool that registers for services, collects confirmation emails, and logs structured data

The API surface is small. The core loop is three HTTP calls. The inbox handles the rest.

Try it at uncorreotemporal.com — your first inbox is one requests.post() away.

End-to-End Testing with Disposable Email and Playwright

Francisco Perez — Wed, 18 Mar 2026 23:32:19 +0000

The Problem Nobody Wants to Talk About

Most E2E test suites cover the happy path: fill a form, click a button, assert a result. But the moment you need to test a signup flow that ends with an email — a verification link, an OTP, a welcome message — things break down fast.

The flow is deceptively simple in production: user submits email → system sends message → user clicks link → access granted. In a test environment, that middle step is a black box. Your Playwright test has no way to receive email natively. And end-to-end testing email is one of those problems that teams defer until a critical bug slips past QA.

The common workarounds:

Mocking the email sender — your tests pass, but you've never verified that the real SMTP path works.
A shared test inbox — fragile, pollutes state across test runs, requires cleanup discipline nobody enforces.
Hardcoded OTP bypass codes — shipping test backdoors into production code.
Internal Mailhog/Mailpit setups — one more service to maintain, and they don't test real SMTP delivery.

Each of these introduces a different kind of lie into your test suite. You're testing the logic, not the system.

Why Traditional Approaches Fail

Mocking doesn't validate delivery

When you mock your email sender (replacing SMTP with a no-op or a spy), you verify that your application called the send function. You don't verify that the email was actually generated, that the template rendered correctly, or that the SMTP configuration is valid.

Real failures — DNS misconfiguration, SPF rejections, broken HTML templates — only surface when you actually send mail. Mocking hides all of this.

Shared inboxes make tests non-deterministic

Multiple tests running in parallel against the same inbox create race conditions. Test A registers, test B registers, both wait for email — and the first email that arrives gets claimed by whichever poll runs first. Flaky tests are the result.

Maintenance overhead compounds

Internal email servers (Mailhog, Mailpit, smtp4dev) need to be deployed, versioned, and kept in sync with your test infrastructure. They have their own APIs, different from production. Your test helpers diverge from real-world behavior. Over time, they become a source of friction rather than a solution.

The Better Approach: Disposable Email + Real Infrastructure

The right model is: one temporary inbox per test, provisioned via API, receiving real SMTP delivery, automatically expiring after the test completes.

This is identical to how production users interact with your system — they have an email address, your app sends to it, they receive it. The only difference is that the inbox is created programmatically, scoped to one test run, and deleted (or allowed to expire) afterward.

A temporary email API lets you:

Create an isolated inbox with a single HTTP call
Poll or stream for incoming messages
Extract OTP codes and verification links from message bodies
Clean up after each test without side effects

No shared state. No mocking. No bypass codes.

Architecture Overview

The infrastructure behind this involves several components working in sequence.

Inbox creation happens via a REST API call. The API generates a unique address in the format <adjective>-<noun>-<number>@<domain> (e.g., crisp-falcon-77@uncorreotemporal.com), stores it in PostgreSQL with an expiration timestamp, and returns the address to the caller.

Email ingestion uses an aiosmtpd-based SMTP server running alongside the API. When mail arrives for a known domain, the handler parses the raw RFC 2822 bytes, extracts headers and body (plaintext and HTML), stores the message in the database, and publishes a new_message event to a Redis pub/sub channel keyed by inbox address. Invalid recipients are silently accepted — returning 250 regardless prevents retry storms from external senders.

Retrieval supports two patterns: polling via REST (GET /api/v1/mailboxes/{address}/messages) and real-time push via WebSocket (WS /ws/inbox/{address}?api_key=<key>). The WebSocket stream emits {"event": "new_message", "message_id": "<uuid>"} when email arrives. The full message body — body_text, body_html, attachments metadata — is fetched separately.

Expiration runs as a background task inside the API process, executing every 60 seconds. Inboxes where expires_at <= now() are soft-deleted. Messages are retained for the configured retention period; the inbox simply stops accepting new mail.

Step-by-Step: Testing with Playwright

Let's walk through a complete Playwright email testing flow using the REST API.

Create a Temporary Inbox

Before your test starts, provision a dedicated inbox:

const API_KEY = process.env.UCT_API_KEY; // uct_<token>
const BASE_URL = "https://uncorreotemporal.com/api/v1";

async function createInbox(ttlMinutes = 15) {
  const res = await fetch(`${BASE_URL}/mailboxes`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": API_KEY,
    },
    body: JSON.stringify({ ttl_minutes: ttlMinutes }),
  });
  const data = await res.json();
  return data; // { address, expires_at }
}

The returned address is what you feed into your signup form. No hardcoded emails.

Trigger the Signup Flow with Playwright

test("signup email verification", async ({ page }) => {
  const { address } = await createInbox();

  await page.goto("https://yourapp.com/signup");
  await page.fill('[name="email"]', address);
  await page.fill('[name="password"]', "Test1234!");
  await page.click('[type="submit"]');

  await page.waitForSelector(".signup-success");
  // Now wait for the verification email
});

At this point, your application has sent a verification email to the temporary inbox. Real SMTP delivery, real message in the queue.

Wait for the Email to Arrive

Use a polling helper with a timeout:

async function waitForEmail(address, { timeout = 30000, interval = 2000 } = {}) {
  const deadline = Date.now() + timeout;

  while (Date.now() < deadline) {
    const res = await fetch(`${BASE_URL}/mailboxes/${address}/messages`, {
      headers: { "X-API-Key": API_KEY },
    });
    const { messages } = await res.json();

    if (messages.length > 0) {
      const msgRes = await fetch(
        `${BASE_URL}/mailboxes/${address}/messages/${messages[0].id}`,
        { headers: { "X-API-Key": API_KEY } }
      );
      return msgRes.json();
    }

    await new Promise((r) => setTimeout(r, interval));
  }

  throw new Error(`No email arrived within ${timeout}ms`);
}

Extract the OTP or Verification Link

function extractVerificationLink(message) {
  const body = message.body_text || "";
  const match = body.match(/https:\/\/yourapp\.com\/verify\?token=[a-zA-Z0-9_-]+/);
  if (!match) throw new Error("Verification link not found in email body");
  return match[0];
}

function extractOTP(message) {
  const body = message.body_text || "";
  const match = body.match(/\b(\d{6})\b/);
  if (!match) throw new Error("OTP not found in email body");
  return match[1];
}

Complete the Verification Flow

  const email = await waitForEmail(address);
  const verificationLink = extractVerificationLink(email);

  await page.goto(verificationLink);
  await expect(page.locator(".verified-badge")).toBeVisible();
});

Full End-to-End Script

import { test, expect } from "@playwright/test";

const API_KEY = process.env.UCT_API_KEY;
const BASE = "https://uncorreotemporal.com/api/v1";

async function apiFetch(path, opts = {}) {
  return fetch(`${BASE}${path}`, {
    ...opts,
    headers: { "X-API-Key": API_KEY, "Content-Type": "application/json", ...opts.headers },
  }).then((r) => r.json());
}

async function createInbox() {
  return apiFetch("/mailboxes", { method: "POST", body: JSON.stringify({ ttl_minutes: 15 }) });
}

async function waitForEmail(address, timeout = 30000) {
  const deadline = Date.now() + timeout;
  while (Date.now() < deadline) {
    const { messages } = await apiFetch(`/mailboxes/${address}/messages`);
    if (messages?.length > 0) return apiFetch(`/mailboxes/${address}/messages/${messages[0].id}`);
    await new Promise((r) => setTimeout(r, 2000));
  }
  throw new Error("Email timeout");
}

async function deleteInbox(address) {
  await fetch(`${BASE}/mailboxes/${address}`, { method: "DELETE", headers: { "X-API-Key": API_KEY } });
}

test("full signup + email verification", async ({ page }) => {
  const { address } = await createInbox();

  try {
    await page.goto("https://yourapp.com/signup");
    await page.fill('[name="email"]', address);
    await page.fill('[name="password"]', "Secure1234!");
    await page.click('[type="submit"]');
    await page.waitForSelector(".check-your-email");

    const email = await waitForEmail(address);
    const [link] = email.body_text.match(/https:\/\/yourapp\.com\/verify\?token=\S+/) || [];
    if (!link) throw new Error("No verification link");

    await page.goto(link);
    await expect(page.locator("h1")).toHaveText("Account verified");
  } finally {
    await deleteInbox(address);
  }
});

CI/CD Integration

This pattern fits naturally into any CI pipeline. Set UCT_API_KEY as a secret, and your tests run identically in local, staging, and CI environments.

# .github/workflows/e2e.yml
- name: Run E2E tests
  env:
    UCT_API_KEY: ${{ secrets.UCT_API_KEY }}
  run: npx playwright test

Key benefits for QA teams:

No shared infrastructure to provision — the email backend is external, always available.
Parallel-safe — each test creates its own inbox; no inbox is shared across test runs.
Test reports include real email content — when a test fails, you can inspect the actual message that arrived (or didn't).

Best Practices

Set aggressive timeouts in CI. Transactional email delivery in a test environment should be fast (under 5s). Set your polling timeout to 20–30 seconds and treat any test that takes longer as a potential infrastructure issue, not a Playwright issue.

Retry on network errors, not on missing email. Distinguish between "the API call failed" (retry) and "no email arrived" (fail the test). Swallowing network errors in your wait loop masks real problems.

Create one inbox per test, not one per suite. Sharing an inbox across multiple tests in a suite reintroduces the shared-state problem. The inbox creation API call is fast — there's no meaningful performance tradeoff.

Clean up explicitly. Even though inboxes expire automatically, DELETE /api/v1/mailboxes/{address} in a finally block keeps your account tidy and reduces noise if you're monitoring active inbox counts.

Store the inbox address in test context. If you use Playwright fixtures, create the inbox in a fixture and attach the address to the test context. This makes it easy to log the address when a test fails, so you can inspect the inbox state during debugging.

Conclusion

Email flows are a first-class part of most user journeys — and they deserve first-class test coverage. Mocking the email layer trades realism for convenience, and eventually that tradeoff costs you. A real email lands in a real inbox, and your test suite should be able to verify that.

The approach described here — temporary inbox provisioned per test, real SMTP delivery, polling or WebSocket retrieval, explicit cleanup — is production-grade and CI-ready. It requires no additional infrastructure on your end and no changes to your application code.

If you want to try this approach, you can use a temporary email API like uncorreotemporal.com to get started.