DEV Community: BeilunYang

Your AI agent can fill in a signup form. It can't read the verification email.

BeilunYang — Mon, 28 Sep 2026 16:46:48 +0000

Ask Claude, Cursor or Codex to sign up for something and it will happily fill in the form. Then it hits the wall every signup flow has: "We've sent you a code. Check your inbox."

The agent has no inbox. So it stops, and asks you to go and copy a six-digit number out of your email. The one step that actually proves the flow works is the one it can't do.

This post is about closing that gap with an MCP server — and about a couple of design decisions that matter more than they look when the caller is an LLM rather than a person.

What we want the agent to do

Four steps, end to end:

Create a throwaway mailbox and get its address.
Type that address into the signup form.
Wait for the verification email to arrive.
Read it, pull out the code, and delete the mailbox.

Steps 2 and 4 the agent already handles. Steps 1 and 3 need tools.

Plugging in an inbox

MoeMail is an open-source temporary email service, and it ships an MCP server as an npm package, @moemail/mcp. It runs locally over stdio via npx, so there is nothing to deploy or keep running.

For Claude Desktop, Cursor and Windsurf, the config block is identical:

{
  "mcpServers": {
    "moemail": {
      "command": "npx",
      "args": ["-y", "@moemail/mcp"],
      "env": {
        "MOEMAIL_API_KEY": "mk_••••••••••••"
      }
    }
  }
}

Claude Code takes the same thing as one command:

claude mcp add moemail -e MOEMAIL_API_KEY=mk_•••••••••••• -- npx -y @moemail/mcp

The server registers eight tools: create_email, wait_for_email, list_messages, read_message, list_emails, send_email, delete_message and delete_email.

What a session actually looks like

You say: "Sign up for the beta at example.com with a throwaway address and tell me the code."

The agent creates a mailbox:

create_email { "expiry": "1h" }
→ { "id": "k3f…", "address": "x7q2m9@moemail.app", "expiresAt": "…T15:04:05.000Z" }

It types x7q2m9@moemail.app into the form and submits. Then it waits:

wait_for_email { "emailId": "k3f…", "timeoutSec": 90 }
→ { "status": "received", "elapsedSec": 12,
    "message": { "messageId": "m81…", "from": "no-reply@example.com",
                 "subject": "Your code is 482913", "receivedAt": "…" } }

It reads the message, finds 482913, finishes the signup, and calls delete_email so nothing is left behind. Four tool calls, plus however many polls the mail takes to land.

The design decision that makes it work: timeouts are not errors

The interesting tool is wait_for_email.

A naive "check inbox" tool returns immediately: empty, or not. That leaves the polling loop to the model, and models are bad at patience. They check once, see nothing, and either give up or invent a reason the email never came.

So wait_for_email blocks for up to 90 seconds, polling the inbox for the agent, and when nothing arrives it does not throw. It returns:

{ "status": "timeout" }

That one choice changes the agent's behaviour. An error reads as "something is broken, stop". A timeout status reads as "not yet", and the natural next move is to call the tool again — which is exactly right, because slow transactional mail is normal and not a failure.

If you are writing tools for agents, this generalises: return expected, recoverable states as data, not as exceptions. Save errors for things the agent should actually stop on, like a bad API key.

Same thing from a shell

Not every agent lives in a chat window. For CI jobs and shell-driven agents there is a CLI, @moemail/cli, where every command takes --json:

npm i -g @moemail/cli
moemail config set api-key mk_••••••••••••

moemail create --expiry 1h --json
# {"id":"k3f…","address":"x7q2m9@moemail.app","expiresAt":"…"}

moemail wait --email-id k3f… --timeout 120 --json
moemail read --email-id k3f… --message-id m81… --json
moemail delete --email-id k3f…

The exit codes are deliberate: 1 is a runtime error (including a wait that timed out), 2 is a configuration or auth error. A script can tell "no mail yet" apart from "wrong key" without parsing anything.

The CLI can also install a skill file, so Claude Code or Codex already knows the create → wait → read → delete loop before you ask:

moemail skill install   # auto-detects Claude Code and Codex

Where this is genuinely useful

Testing your own signup and onboarding flows. Have an agent walk through registration on your staging environment after each deploy and confirm the verification email arrives and the code works.
Agent-driven QA of password reset, magic links and email-change confirmations — the flows that are tedious to click through by hand and easy to break.
Trying out a tool without handing over your real address, where the service's terms allow it.

Where it isn't

It is worth saying plainly: a throwaway inbox for an agent is not a licence to mass-create accounts, farm free trials, or get around a platform's limits. Plenty of services forbid that in their terms and actively detect it. Point this at systems you own or are allowed to test, and respect the rules of the ones you don't.

Cost and self-hosting

The MCP server and CLI are MIT-licensed and free to install. Calling the MoeMail API needs a key with quota, and API access is a paid add-on — the default plan has no free API calls. Budget for polling: every poll wait_for_email makes is one API call, so a typical round trip is four calls plus the polls. The web inbox itself is free.

If you would rather not depend on a hosted service at all, MoeMail is open source and runs on Cloudflare Workers. Point the packages at your own instance with MOEMAIL_API_URL; they default to moemail.app.

Full client configs (including Codex) and the complete tool list are on the MCP page. The source for both packages lives in the repository under packages/mcp and packages/cli.

Playwright Email Testing: A Real End-to-End Tutorial (No Mocks)

BeilunYang — Sat, 29 Aug 2026 15:31:06 +0000

Most "email testing" advice ends at stubbing the send call. You assert that your
app tried to send a message, and the test goes green. That leaves the
interesting half untested: whether the message actually left your infrastructure,
whether the template rendered, and whether the six-digit code inside it matches
the one your backend is willing to accept.

This walks through the other approach — driving a real signup flow in
Playwright, letting a real email get delivered to a
real inbox, then reading it back over an API and typing the code into the page.
No mail server to run, no shared QA mailbox to clean up.

The shape of the problem

A verification-email test has four moving parts:

an address that is unique to this test run,
the browser flow that triggers the send,
a way to read the message that arrives,
code extraction and the assertion.

Steps 1 and 3 are the ones people get wrong, and they get them wrong in the same
way: by sharing one mailbox across the suite. The moment two tests run in
parallel, one of them reads the other's email. So the rule is one inbox per
test, provisioned on the fly and thrown away afterwards.

The inbox helper

Any disposable-inbox API with a REST interface works here. I'll use
MoeMail's because it's open source and the free tier is
enough for a CI suite — the shape is the same anywhere, so swap the base URL and
the auth header if you use something else.

// inbox.ts
const API = 'https://moemail.app/api'
const KEY = process.env.MAIL_KEY!

export type Inbox = { id: string; email: string }

export async function createInbox(ttlMs = 3_600_000): Promise<Inbox> {
  const res = await fetch(`${API}/emails/generate`, {
    method: 'POST',
    headers: { 'X-API-Key': KEY, 'Content-Type': 'application/json' },
    // Omit `name` and a random local part is generated for you — which is
    // exactly what you want, so parallel tests can never collide.
    body: JSON.stringify({ expiryTime: ttlMs, domain: 'moemail.app' }),
  })
  if (!res.ok) throw new Error(`create inbox failed: ${res.status}`)
  return res.json() // { id, email }
}

export type Message = {
  id: string
  from_address: string
  subject: string
  content: string
  html: string | null
  received_at: number
}

export async function waitForMessage(
  inboxId: string,
  { timeoutMs = 30_000, intervalMs = 1_500 } = {},
): Promise<Message> {
  const deadline = Date.now() + timeoutMs
  while (Date.now() < deadline) {
    const res = await fetch(`${API}/emails/${inboxId}`, {
      headers: { 'X-API-Key': KEY },
    })
    if (!res.ok) throw new Error(`poll failed: ${res.status}`)
    const { messages } = await res.json()
    if (messages?.length) return messages[0]
    await new Promise(r => setTimeout(r, intervalMs))
  }
  throw new Error(`no email arrived within ${timeoutMs}ms`)
}

Two details worth keeping. expiryTime is in milliseconds, and the poll loop
is bounded by a deadline rather than a fixed retry count — a fixed count silently
becomes a different timeout the moment you change the interval.

Wiring it into a Playwright fixture

Doing this in the test body works, but it puts transport concerns in front of
behaviour. A fixture hides it, and gives every test a fresh address without
anyone having to remember:

// fixtures.ts
import { test as base } from '@playwright/test'
import { createInbox, type Inbox } from './inbox'

export const test = base.extend<{ inbox: Inbox }>({
  inbox: async ({}, use) => {
    await use(await createInbox())
  },
})

export { expect } from '@playwright/test'

Now the test reads like the user story it represents:

import { test, expect } from './fixtures'
import { waitForMessage } from './inbox'

test('a new user can verify their email', async ({ page, inbox }) => {
  await page.goto('/signup')
  await page.getByLabel('Email').fill(inbox.email)
  await page.getByRole('button', { name: 'Sign up' }).click()

  const msg = await waitForMessage(inbox.id)

  const code = msg.content.match(/\b\d{6}\b/)?.[0]
  expect(code, `no 6-digit code in: ${msg.subject}`).toBeDefined()

  await page.getByLabel('Verification code').fill(code!)
  await expect(page.getByText('Welcome')).toBeVisible()
})

Note the expect on the extraction itself. match(...)[0] throws
Cannot read properties of null when the regex misses, and you get a stack trace
pointing at the regex instead of the actual failure, which is that the email said
something you didn't expect. Asserting with the subject line in the message turns
ten minutes of confusion into one glance at the report.

Magic links instead of codes

Same fixture, different extraction — pull the URL out and navigate straight to it:

const link = msg.content.match(/https:\/\/[^\s"<>]+\/verify\?[^\s"<>]+/)?.[0]
expect(link).toBeDefined()
await page.goto(link!)

If your template only puts the link in the HTML part, read msg.html instead of
msg.content — plain-text alternatives get out of sync with the HTML more often
than anyone expects, and testing the part users actually click is the point.

Making it survive CI

A few things that turned flaky runs into boring ones for me:

Never share an address across tests. The fixture already handles it; the failure mode when you don't is a test that passes alone and fails in a suite.
Prefer a webhook over polling if latency matters. Polling is simpler and fine for a handful of tests; a push means you react the instant mail lands instead of waiting out an interval.
Keep the timeout tight but honest. 30s covers real delivery. If you need 90s, you have a delivery problem that a longer timeout is hiding, not fixing.
Put the API key in CI secrets, not in playwright.config.ts. Obvious, and still the most common thing I see committed.

The same recipe elsewhere

Nothing above is Playwright-specific except the fixture wiring. The two helpers
drop into Cypress or Selenium unchanged — only the way you register them differs.

If you're currently paying for a hosted inbox service, this is also roughly the
whole migration: the fixture is the seam, and only the transport behind it
changes. I wrote up how the options compare —
Mailosaur and MailSlurp alternatives that receive real email
— including which of them can't actually accept mail from the public internet,
which is the distinction most comparison posts skip.

Full API reference is in the OpenAPI docs,
and the server itself is on
GitHub under MIT if you'd rather
self-host it and point the same tests at your own domain.