Temporary email for AI agents
Create a receive-only inbox for development or QA work you are authorized to perform. Read messages, extracted verification codes, and links using the access token returned at creation. Never put the token in a prompt, public log, or repository.
Working with HTTP or a terminal instead of an MCP client? Start with the free temporary email API: one-request inbox creation, or use the installable Python and Node clients. No account or global API key is required.
1. Connect your agent
Use https://gecici.email/mcp as a remote HTTP MCP server. No account, global API key or server package is required. Each new inbox returns its own access token; keep it with the address in private runtime state.
Claude Code
claude mcp add --transport http gecici-email https://gecici.email/mcp
claude mcp get gecici-email
Cursor
Merge this entry into your project's .cursor/mcp.json, preserving existing servers:
{
"mcpServers": {
"gecici-email": { "url": "https://gecici.email/mcp" }
}
}
Refresh tool discovery. The seven tools should include gecici_create_inbox, gecici_wait_for_verification and gecici_delete_inbox. Saving a URL is only the connection step.
Configuration formats were checked against the Claude Code documentation and Cursor documentation. The connected-tool check below used Codex; it does not establish a completed Claude or Cursor model run.
2. Finish your first application verification task
Python 3.9+ · no extra packages · QA simulation. A local application creates a one-use challenge and inserts a fictional message into a hosted inbox created through MCP. A separate client extracts the code through MCP. The application checks the submitted code against its own record, then the inbox is deleted. This does not use SMTP or create a real account.
Review and download agent-first-task.py, then run:
python3 agent-first-task.py --run
connection / inbox_created / mail_simulated- Separate outcomes for connection, inbox creation and simulated mail insertion.
value_extracted / application_accepted- Finding a code and the application accepting it are separate checks.
wrong_code_rejected / replay_rejected / cleanup- Wrong-code rejection, one-use enforcement and inbox deletion are checked too.
passed: true requires all checks and cleanup to succeed. failed_step identifies where the run stopped. The output contains no addresses, tokens, messages or codes. --run uses a deterministic client; it is not a model test.
3. Try the task with your connected MCP tool
For an agent that can make local HTTP requests, start the fixture in another terminal. It binds only to your computer; never expose this teaching server publicly.
python3 agent-first-task.py --serve
- The agent POSTs an empty JSON object to
http://127.0.0.1:8798/startwithX-QA-Fixture: 1. Keep the returned tool name and arguments in private runtime state; never print or log them. - Call
gecici_wait_for_verificationthrough the agent's connected MCP tool using those arguments. Continue only onready, never on an empty result. - POST
{"code":"the returned test code"}to the same local application's/verifywith the same header. Require HTTP 200 andstate: verified. - Even on failure, POST to
/cleanupand requirecleanup: true. Then stop the server with Ctrl+C.
Finish within 120 seconds. The inbox is created as QA; later authenticated tool calls remain QA even if the connected client does not send the QA header. On 17 November 2026, a Codex connected-MCP tool run extracted the code; the separate local HTTP application accepted it, rejected a wrong code and replay, and cleanup succeeded. This is our test, not acquired usage or external email delivery evidence.
Find the failing step
start- Check the MCP URL and tool discovery. If an inbox was created before simulated mail failed, cleanup still runs. Do not add a global API key.
extract- Use the address and token from the same inbox and its
createdAtassince. Do not count pending as success. For ambiguous or blocked results, inspect matching filters or the message template. application_acceptance- A returned code may be invalid for the application. Check this fixture's 120-second lifetime and five-attempt limit; do not reuse a value from an older run.
cleanup- Each cleanup call makes at most three deletion attempts. If it fails, do not report deletion; retry /cleanup while the local server is running. Never publish the inbox token.
For your own application, replace simulation with the application's actual test email. Give the application only the inbox address. Match the sender, subject and start time, then check the application's explicit success state.
TESTED GUIDE ·
Test temporary email and verification-code tools with browser-use
An agent testing your application's email verification needs to create an inbox, read the incoming code, and delete the inbox when finished. This example registers those three operations as browser-use tools. The bearer token stays inside the Python helper; the agent receives the address and code needed by your form.
The check below dispatches real tools against the hosted API and adds a fictional message through the simulation endpoint. It does not launch a browser, call a language model or use an external email sender. Passing it does not prove that a website signup was completed.
1. Install the tested revision
Use Python 3.11 or later and start in a new directory. No model key or separate gecici-email Python package is required for this check.
git clone https://github.com/codeonthetable/gecici-email.git
cd gecici-email
git checkout 4951b8f041b8ebe9b98282dacbc4c2d262b711b5
python3 -m venv .venv
source .venv/bin/activate
python -m pip install 'browser-use==0.13.11'
python -m unittest discover -s tests -v
python examples/browser_use_inbox.py --qa-run
On Windows, activate with .venv\Scripts\activate. The pinned Git revision downloads the code used for the results below. Review the example source before running it.
2. Understand the result
With Python 3.12.14 and browser-use 0.13.11, 16 local tests passed; the separate opt-in live MCP test was skipped. The hosted API check returned these fields as true. It prints no addresses, tokens, messages or codes.
create_action_passed: true- The tool created a temporary inbox.
token_not_returned: true- The create tool's result did not contain the bearer token.
otp_action_matched: true- The extracted code matched the fictional message inserted by the test.
cleanup: true- The disposable inbox was deleted after the check.
Requests carry the qa-test label. This demonstration is excluded from normal usage; it is not a real user or successful AI-use count. Empty inboxes and timeouts are not successful verification.
3. Connect your own application's test flow
- Create a fresh
InboxTools(qa=True)for each run and add the tools to your existing agent withregister(Tools()). - Ask the agent to call
gecici_create_inboxand enter the returned address into your test form. Keep the bearer token out of the form. - After your application sends its message, call
gecici_wait_for_otpwith a timeout from 1 to 45 seconds. Enter the received code and check your application's explicit success state. - Call
gecici_delete_inboxand also useawait inbox.close()in your runner'sfinallyblock.
This adaptation needs your actual test application URL, a browser setup and a configured model. The full model-and-form workflow has not been tested for this guide. Your model can see the address and code, so use fictional test data and review your agent's history settings.
Agent integration code and test details →
No code arrived: what to check
| Result | Next check |
|---|---|
| Deadline reached | Check your application's send result and delivery delay. Do not mark the form verified before a code arrives. |
| Inbox action failed | Check connectivity, expiry and parameters. Use a fresh helper for a new run. |
| Deletion failed | Retry await inbox.close() on the same helper. Failed deletion keeps the token in memory for retry. |
The tools follow browser-use's custom-tool API. This example is published in the gecici.email repository; it does not imply browser-use endorsement or an accepted upstream contribution.
Get the right verification result in one call
gecici_wait_for_verification waits for a matching message and extracts its code, HTTPS link, or both. It returns a small structured result instead of the email body. Use a fresh inbox for each test, then pass its createdAt as since.
{
"name": "gecici_wait_for_verification",
"arguments": {
"address": "<created inbox>",
"token": "<inbox token>",
"since": 0,
"kind": "either",
"sender": "qa@example.invalid",
"subject_contains": "Verify your email",
"expected_link_host": "app.example.invalid",
"timeout_seconds": 15
}
}Replace since: 0 with the inbox's actual createdAt Unix milliseconds, and replace the example sender, subject and host with your application's values. For an existing inbox, use the start time of the new verification attempt. Sender and subject filters apply together. Sender matching does not authenticate the email sender.
| State | What your agent should do |
|---|---|
ready | Use the extracted value in your authorized application, then check that application's success state. |
pending | No matching supported value yet. Retry within your test's deadline, at most three calls in the example workflow. |
ambiguous | Multiple codes or allowed links. No value is returned; narrow the test or inspect the template. |
blocked | Link host/scheme mismatch or a processing limit. Check reason; do not automatically widen the allowed host. |
Codes need a supported English or Turkish verification label. Links work in plain text and HTML; link mode requires an exact host and HTTPS. No links are opened. Extraction is deterministic, not a guarantee that a code is valid, a sender is genuine, or an application accepted verification.
Download the self-contained verification example and run python3 mcp-verification.py --run. It tests matching, plain-text links, ambiguous codes, host rejection and cleanup with fictional QA messages. No account or package installation is required. This tests the hosted API, not external SMTP or an LLM. Refresh MCP tool discovery if your client still shows six tools.
REST integration
The REST base is https://gecici.email/api/v1. Create an inbox with POST /inbox/generate or POST /inbox/custom. Then pass Authorization: Bearer <token> when reading, extending, or deleting that inbox.
Check the application result
Run the tested email verification form: a Python application and real Chrome form check wrong codes, verification, reuse rejection and cleanup with a hosted QA inbox. Message transport is simulated; no SMTP or LLM run is claimed.
Downloadable clients
The public GitHub repository provides a runnable client and integration material. It does not provide the private hosted server source. Check the repository's current setup instructions before integrating.
Minimal protocol check
Download mcp-quickstart.py and run python3 mcp-quickstart.py --run. It uses Python’s standard library, initializes MCP, creates an inbox, reads a fictional message and deletes the inbox through MCP. No account, global API key or installed package is needed.
This is a QA simulation, not an external email or model test. All requests carry qa-test; addresses, tokens and messages are never printed.
Finish the inbox lifecycle
After reading your test message, call gecici_delete_inbox with that inbox’s address and token. A successful result contains deleted: true. This deletes the active inbox and its messages; it is not a promise of physical erasure from backups or logs.
Successful MCP tools provide both JSON text and structuredContent. Check isError first; empty and timed-out reads are not completed verification.
Operational limits
- Receive-only; no outbound email.
- Default inbox lifetime: 60 minutes; token holder may extend or delete.
- External delivery, verification acceptance, and third-party service behavior are not guaranteed.
- No CAPTCHA or security-control bypass is provided.
Practical setup and troubleshooting guides
Connect Cursor to MCP · Run a Playwright verification test · Diagnose missing mail