DEV Community: Diego Ramos

How to Use Disposable Email in Your CI/CD Pipeline for E2E Testing

Diego Ramos — Thu, 21 May 2026 02:23:40 +0000

The Problem

You have a signup flow. It sends a verification email. You need to test it end-to-end.

In development, you probably skip email verification with a flag, or use a shared test inbox that everyone on the team reads from. In CI, things get worse:

Shared test inboxes create race conditions when parallel jobs read the same messages
Mocking the email service means you're not actually testing email delivery
Skipping verification means you're not testing the real flow
Hardcoded test emails break when someone changes the email template

What you want is: create a fresh inbox, run the test, check for the email, extract the code, verify it works, delete the inbox. All programmatically, all isolated per test run.

The Solution: Disposable Email API

GoneBox provides a REST API for temporary email. No SDK to install for basic usage — just HTTP calls. Create an inbox, get an email address, poll for messages, read them, delete when done.

Here's the full lifecycle:

1. POST /api/v1/inboxes           → Create inbox (get address)
2. [Your app sends email to that address]
3. GET  /api/v1/inboxes/:addr/messages  → Poll until message arrives
4. GET  /api/v1/messages/:id      → Read the full email
5. [Extract code/link, verify it works]
6. DELETE /api/v1/inboxes/:addr   → Cleanup

Inboxes auto-expire after 1 hour anyway, but explicit cleanup keeps things tidy.

Example: Playwright + GoneBox API

Here's a real E2E test for a signup flow using Playwright:

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

const API_BASE = 'https://api.gonebox.email/api/v1';

// Helper: create a temp inbox
async function createInbox(): Promise<{ address: string }> {
  const res = await fetch(`${API_BASE}/inboxes`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ domain: 'gonebox.email' }),
  });
  const data = await res.json();
  return { address: data.address };
}

// Helper: wait for an email to arrive
async function waitForEmail(
  address: string,
  timeoutMs = 30_000,
  pollMs = 2_000,
): Promise<any> {
  const deadline = Date.now() + timeoutMs;
  const encoded = encodeURIComponent(address);

  while (Date.now() < deadline) {
    const res = await fetch(`${API_BASE}/inboxes/${encoded}/messages`);
    const data = await res.json();
    const messages = Array.isArray(data) ? data : data.messages ?? [];

    if (messages.length > 0) {
      // Fetch full message content
      const msgRes = await fetch(`${API_BASE}/messages/${messages[0].id}`);
      return await msgRes.json();
    }

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

  throw new Error(`No email received at ${address} within ${timeoutMs}ms`);
}

// Helper: extract verification code from email body
function extractCode(text: string): string | null {
  const match = text.match(
    /(?:code|verify|otp|pin)\s*[:=\-]?\s*(\d{4,8})/i,
  );
  return match ? match[1] : null;
}

// Helper: cleanup
async function deleteInbox(address: string): Promise<void> {
  const encoded = encodeURIComponent(address);
  await fetch(`${API_BASE}/inboxes/${encoded}`, { method: 'DELETE' });
}

test('signup with email verification', async ({ page }) => {
  // 1. Create a disposable inbox
  const { address } = await createInbox();

  try {
    // 2. Fill the signup form
    await page.goto('https://your-app.com/signup');
    await page.fill('[name="email"]', address);
    await page.fill('[name="password"]', 'TestPassword123!');
    await page.click('button[type="submit"]');

    // 3. Wait for verification email
    await expect(page.locator('.check-email-message')).toBeVisible();
    const email = await waitForEmail(address);

    // 4. Extract and enter verification code
    const code = extractCode(email.body_text);
    expect(code).not.toBeNull();

    await page.fill('[name="verification-code"]', code!);
    await page.click('button[type="submit"]');

    // 5. Verify successful signup
    await expect(page).toHaveURL(/\/dashboard/);
    await expect(page.locator('h1')).toContainText('Welcome');
  } finally {
    // 6. Always cleanup
    await deleteInbox(address);
  }
});

Key points:

Each test gets its own inbox — no shared state, no race conditions
The finally block ensures cleanup even if the test fails
Polling interval of 2 seconds keeps the test responsive without hammering the API
The timeout is configurable per test

Example: Jest + Node.js (API-Only Testing)

If you're testing email delivery without a browser:

import { describe, it, expect, afterEach } from '@jest/globals';

const API_BASE = 'https://api.gonebox.email/api/v1';
let testInbox: string | null = null;

afterEach(async () => {
  if (testInbox) {
    const encoded = encodeURIComponent(testInbox);
    await fetch(`${API_BASE}/inboxes/${encoded}`, { method: 'DELETE' });
    testInbox = null;
  }
});

async function createTestInbox(): Promise<string> {
  const res = await fetch(`${API_BASE}/inboxes`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ domain: 'gonebox.email' }),
  });
  const data = await res.json();
  testInbox = data.address;
  return data.address;
}

async function pollForMessage(address: string, maxWaitMs = 15_000) {
  const encoded = encodeURIComponent(address);
  const deadline = Date.now() + maxWaitMs;

  while (Date.now() < deadline) {
    const res = await fetch(`${API_BASE}/inboxes/${encoded}/messages`);
    const data = await res.json();
    const messages = Array.isArray(data) ? data : data.messages ?? [];

    if (messages.length > 0) return messages[0];
    await new Promise((r) => setTimeout(r, 2_000));
  }
  return null;
}

describe('Email delivery', () => {
  it('sends welcome email after user creation', async () => {
    const email = await createTestInbox();

    // Trigger your API to send an email
    const res = await fetch('https://your-api.com/users', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        email,
        name: 'Test User',
      }),
    });
    expect(res.status).toBe(201);

    // Wait for the email
    const message = await pollForMessage(email);
    expect(message).not.toBeNull();
    expect(message.subject).toContain('Welcome');
  }, 30_000); // 30s timeout for the whole test

  it('sends password reset email', async () => {
    const email = await createTestInbox();

    await fetch('https://your-api.com/auth/forgot-password', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email }),
    });

    const message = await pollForMessage(email);
    expect(message).not.toBeNull();
    expect(message.subject).toMatch(/reset|password/i);
  }, 30_000);
});

CI Configuration

GitHub Actions

name: E2E Tests
on: [push]

jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci
      - run: npx playwright install --with-deps

      # No special setup needed — GoneBox API is a public service
      - run: npx playwright test
        env:
          GONEBOX_API_URL: https://api.gonebox.email
          # Optional: use API key for higher rate limits
          # GONEBOX_API_KEY: ${{ secrets.GONEBOX_API_KEY }}

No Docker containers to spin up. No SMTP server to configure. No ports to expose. The API is remote, so your CI just makes HTTP calls.

GitLab CI

e2e-tests:
  image: mcr.microsoft.com/playwright:v1.40.0-focal
  script:
    - npm ci
    - npx playwright test
  variables:
    GONEBOX_API_URL: https://api.gonebox.email

Practical Tips

1. Use unique inboxes per test. Don't pass a custom username — let the API generate a random one. This prevents collisions between parallel test runs.

2. Set reasonable timeouts. Email delivery usually takes 2-10 seconds. A 30-second timeout is safe for CI; 60 seconds if your email provider is slow.

3. Clean up in afterEach/finally. Inboxes auto-expire after 1 hour, but explicit cleanup prevents hitting the 3-inbox-per-IP limit during large test suites.

4. Use API keys for CI. The public tier allows 60 requests/minute. If you have many email tests running in parallel, get an API key for higher limits.

5. Don't test email rendering here. This approach tests delivery and content. For rendering (does the email look right in Gmail/Outlook), use dedicated tools like Litmus or Email on Acid.

What About Alternatives?

Approach	Pros	Cons
Mock email service	Fast, deterministic	Not testing real delivery
Shared test inbox	Simple setup	Race conditions, no isolation
Mailtrap/Mailhog	Full SMTP control	Requires SMTP config changes per env
GoneBox API	No config changes, isolated per test	Depends on external service

GoneBox works well when you want to test the actual email delivery path without modifying your application's email configuration. Your app sends to a real email address; the test reads from the API.

If you need full SMTP control (testing DKIM, SPF, bounce handling), you'll want Mailtrap or a similar tool instead.

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

Diego Ramos — Thu, 21 May 2026 02:19:46 +0000

The Problem

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

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

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

What MCP Gives Us

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

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

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

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

Setup

Add the server to your claude_desktop_config.json:

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

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

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

The Tools

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

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

Real Workflow: Email Verification

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

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

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

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

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

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

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

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

How extract_verification_code Works

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

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

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

How extract_link Works

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

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

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

Using the REST API Directly

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

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

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

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

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

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

Architecture

The stack is designed around being cheap to operate:

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

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

What It Doesn't Do

Being transparent about limitations:

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

Why I Built This

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

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

Try It

Website: gonebox.email
API docs: gonebox.email/api-docs
MCP Server: npx @gonebox/mcp-server
Source: The MCP server is MIT licensed

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

DEV Community: Diego Ramos

How to Use Disposable Email in Your CI/CD Pipeline for E2E Testing

The Problem

The Solution: Disposable Email API

Example: Playwright + GoneBox API

Example: Jest + Node.js (API-Only Testing)

CI Configuration

GitHub Actions

GitLab CI

Practical Tips

What About Alternatives?

Links

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

The Problem

What MCP Gives Us

Setup

The Tools

Real Workflow: Email Verification

How extract_verification_code Works

How extract_link Works

Using the REST API Directly

Architecture

What It Doesn't Do

Why I Built This

Try It