fabricatedemail

Test email verification with OpenCode

OpenCode can run your signup or password-reset flow end to end: it registers a disposable email address, drives your app, waits for the mail, extracts the one-time code and asserts on it. No inbox screenshots, no regular expressions, no shared test mailbox.

This guide connects the fabricatedemail MCP server to OpenCode and walks through one complete loop. It takes an API key and about five minutes.

What you need

1. Connect the MCP server

Add the server to opencode.json in the project root, with the key read from an environment variable:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "fabricatedemail": {
      "type": "remote",
      "url": "https://api.fabricatedemail.com/mcp",
      "enabled": true,
      "headers": { "Authorization": "Bearer {env:FABRICATEDEMAIL_KEY}" }
    }
  }
}

Export FABRICATEDEMAIL_KEY in the shell you start OpenCode from. The six tools appear as fabricatedemail_create_address, fabricatedemail_wait_for_message, fabricatedemail_extract, fabricatedemail_get_message, fabricatedemail_list_addresses, fabricatedemail_delete_address.

2. Run the loop

Ask OpenCode to test the flow. A prompt like this is enough:

Register a disposable email address with fabricatedemail, sign up for the app at http://localhost:3000/signup with that address, wait for the verification mail, extract the code, submit it on the verification page, and confirm the account is active. Delete the address when you're done.

What the agent does, tool by tool:

  1. create_address — registers an address and returns its subscriptionId and the address itself, e.g. 8f2c1d94a7b30e56@fabricatedemail.com. Let the tool generate the local part; a hand-picked one can collide with another agent's.
  2. Drives your signup with that address — with Playwright, a curl, or whatever the agent has at hand.
  3. wait_for_message with waitSeconds: 30 — the call holds open until the mail lands.
  4. extract on that message — returns the one-time codes and links found in it, so the agent does not have to parse the body.
  5. Submits the code, checks the result.
  6. delete_address — live addresses count against your account cap across every key, so the agent should clean up.

3. Put it in CI (optional)

The same loop runs headless. Give the CI job its own key as FABRICATEDEMAIL_KEY, and either let the agent run it or call the HTTP API directly from your test — the tools are the same endpoints. The getting started page has the curl version.

When the mail does not arrive

wait_for_message returning nothing after 30 seconds almost always means the mail was rejected before it reached us. Mail must pass SPF or DKIM and the sender's DMARC policy; mail from a local dev server without those records is rejected at the edge. Send through a provider with the DNS records in place (SES, SendGrid, Postmark, Azure ACS) or point your dev environment at one. Why mail might not arrive lists every case in the order worth checking.

Limits that apply to the agent

The MCP tools are the HTTP API: same key, same caps, same 24-hour retention, same 30-second long poll. Each tool call counts as one request against the rate limit. See pricing for the tiers.