← gecici.email

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
  1. The agent POSTs an empty JSON object to http://127.0.0.1:8798/start with X-QA-Fixture: 1. Keep the returned tool name and arguments in private runtime state; never print or log them.
  2. Call gecici_wait_for_verification through the agent's connected MCP tool using those arguments. Continue only on ready, never on an empty result.
  3. POST {"code":"the returned test code"} to the same local application's /verify with the same header. Require HTTP 200 and state: verified.
  4. Even on failure, POST to /cleanup and require cleanup: 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 createdAt as since. 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

  1. Create a fresh InboxTools(qa=True) for each run and add the tools to your existing agent with register(Tools()).
  2. Ask the agent to call gecici_create_inbox and enter the returned address into your test form. Keep the bearer token out of the form.
  3. After your application sends its message, call gecici_wait_for_otp with a timeout from 1 to 45 seconds. Enter the received code and check your application's explicit success state.
  4. Call gecici_delete_inbox and also use await inbox.close() in your runner's finally block.

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

ResultNext check
Deadline reachedCheck your application's send result and delivery delay. Do not mark the form verified before a code arrives.
Inbox action failedCheck connectivity, expiry and parameters. Use a fresh helper for a new run.
Deletion failedRetry 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.

REST and MCP API guide · Türkçe rehber

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.

StateWhat your agent should do
readyUse the extracted value in your authorized application, then check that application's success state.
pendingNo matching supported value yet. Retry within your test's deadline, at most three calls in the example workflow.
ambiguousMultiple codes or allowed links. No value is returned; narrow the test or inspect the template.
blockedLink 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.

Read the English API guide.

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

Practical setup and troubleshooting guides

Connect Cursor to MCP · Run a Playwright verification test · Diagnose missing mail