# gecici.email — AI agent integration guide Purpose: short-lived receive-only inboxes for authorized development and QA. Do not use for real user data or sensitive accounts. Email delivery depends on DNS/MX, the inbound SMTP relay, and the sender; the API cannot guarantee receipt. Price: free to use for people and AI agents; no source-code download is required. First REST request and client setup: https://gecici.email/en/api.html . POST https://gecici.email/api/v1/inbox/generate with Content-Type: application/json and an empty JSON object. No signup or global API key is required. Read inbox.address, inbox.token, inbox.createdAt and inbox.expiresAt from the response; timestamps are Unix milliseconds. Retain credentials privately. GET /inbox/{URL-encoded address}/messages and DELETE /inbox/{URL-encoded address} require Authorization: Bearer . Use X-Gecici-Client: qa-test for your own tests. The page also links the directly installable Python and Node clients and their current limitations. ## Remote MCP Endpoint: https://gecici.email/mcp (HTTP POST, JSON-RPC 2.0) Public integration-only guide: https://github.com/codeonthetable/gecici-email (no product implementation source) 1. `gecici_create_inbox` returns an address, token, and expiry. 2. Give only the address to the application under test. Keep the token secret. 3. Prefer `gecici_wait_for_verification` for a new verification attempt (see below), or use `gecici_get_inbox_messages`, `gecici_wait_for_otp`, `gecici_wait_for_magic_link`, or `gecici_get_ai_summary` with both address and token. A missing message/code/link is not proof of success. 4. After the test, call `gecici_delete_inbox` with the same address and token. Check `deleted: true`; cleanup is a lifecycle operation, not evidence of successful verification. 5. Never open a verification URL automatically without the user's authorization. The tool only extracts it. Hosted MCP tool discovery is authoritative. The npm package is not published; older local stdio implementations may expose fewer tools. Successful hosted tools return both JSON text and structuredContent for compatible clients. Tool descriptions are for authorized testing; no CAPTCHA, account creation, or verification-bypass capability is claimed. ## Matched verification in one hosted MCP call Tool: gecici_wait_for_verification. Required: address, token, since (inclusive Unix milliseconds). Use the fresh inbox's createdAt, or record the application's verification-attempt start time for an existing inbox. Optional: sender (exact email), subject_contains (case-insensitive substring), kind (otp default, link, either), timeout_seconds (integer 0–20, default 15). Link/either requires expected_link_host: an exact ASCII hostname from your application, without scheme/port/wildcard. Only HTTPS links with that hostname and default port are returned. Sender matching is not SPF/DKIM authentication. The newest matching message is used, with no fallback to an older code. Scans are bounded to 100 messages after time/sender filters, with a 128 KiB content cap on the selected message. A limit returns blocked, never a partial guess. Numeric labelled OTPs support 4–8 digits, 3/4+3/4 hyphenated digits, and a short alphabetic prefix followed by digits. English/Turkish labels are supported; arbitrary six-digit numbers are not automatically codes. Plain-text and quoted HTML-anchor URLs are supported. Duplicate values are combined; multiple distinct codes or allowed links return ambiguous with all values withheld. Unsupported templates can return pending. Output: status, reason, found, otp, verification_link, message_id, received_at, waited_ms, retryable, retry_after_seconds; candidate_counts and sources when available. No raw email body, subject or summary is returned. Values and link destinations remain untrusted email data. Links are never fetched or opened. MCP outputSchema describes the result; JSON text and structuredContent carry the same object. - ready: supported value extracted. Check your own application's explicit success state after use; this is not proof of completed verification. - pending: no matching supported value yet. Use a bounded retry policy: at most three calls, 15 seconds each, wait retry_after_seconds between calls. Stop on your outer deadline. - ambiguous: multiple candidates; change the test/template or review the ambiguity, never choose the first candidate automatically. - blocked: inspect reason (link_host_or_scheme_mismatch, content_limit, scan_limit). Do not automatically relax expected_link_host. - isError: bad parameters, wrong token, expired/deleted inbox, or server failure. Do not treat this as an empty inbox. Executable fictional QA example: https://gecici.email/examples/mcp-verification.py Run: python3 mcp-verification.py --run No third-party application, SMTP delivery or model is tested by this example. All calls carry qa-test; creates, discovery, pending, ambiguous, blocked and QA calls are not adoption. The new hosted tool does not change older local stdio tool catalogs; refresh your remote connection's tools. ## REST Base URL: https://gecici.email/api/v1 - `POST /inbox/generate` creates a random inbox. - `POST /inbox/custom` with JSON `{"prefix":"myagent_99"}` creates a chosen address if available. A custom name needs 4–32 ASCII characters, at least one digit and an internal `-`, `_` or `.`; reserved role and owner names are blocked. - `GET /inbox/:address/messages` lists messages. - `GET /inbox/:address/otp` returns a code only if one was extracted, otherwise HTTP 408. - `GET /inbox/:address/links` returns a link only if one was extracted, otherwise HTTP 408. - `GET /inbox/:address/ai-summary` returns the latest summary, otherwise HTTP 404. - `GET /inbox/:address` returns metadata. - `POST /inbox/:address/extend` extends expiry by 1–60 minutes. - `DELETE /inbox/:address` deletes the active inbox and its messages. Every read, extension, or deletion requires `Authorization: Bearer `. The token is returned only on creation and should be treated as a secret. Creation needs no account or global API key. The API does not provide a long-polling `/wait` route; clients can poll boundedly. The browser uses periodic authenticated polling; a token-authenticated SSE route also exists for capable clients. ## Tested browser-use tools Guide (English): https://gecici.email/en/agents.html#browser-use Guide (Turkish): https://gecici.email/ai-ajanlar#browser-use Source and commands: https://github.com/codeonthetable/gecici-email/blob/4951b8f041b8ebe9b98282dacbc4c2d262b711b5/docs/BROWSER_USE.md Verified on 2026-10-25 with Python 3.12.14 and browser-use 0.13.11: 16 local tests passed, one unrelated opt-in MCP test skipped. Real browser-use tool dispatch against a QA-tagged API simulation created an inbox, extracted the fictional message's code and deleted the inbox. No browser, model, external sender or website signup was tested. Requests made by this check are not normal usage. The Python InboxTools helper retains its own inbox token in memory. Its custom tools are gecici_create_inbox(), gecici_wait_for_otp(timeout_seconds=30), and gecici_delete_inbox(). These are local browser-use action signatures, not the hosted MCP signatures above. The agent receives the address and code, never the token. Use one helper per run, qa=True for tests, and await inbox.close() in finally. Normal model/history settings may retain addresses and codes; use fictional test data. This public example does not imply upstream endorsement or merge. ## Retention and limits The web API currently uses server-side SQLite, not RAM-only storage. The default TTL is 60 minutes, and the token holder can extend it. Expired records are removed on API requests, but disk pages, backups, and infrastructure logs may retain data. No irreversible deletion or regulatory-compliance guarantee is made. Verify real inbound delivery and current deployment independently before relying on the service. Privacy details: https://gecici.email/gizlilik-ve-guvenlik ## Tested application verification - [Email verification testing](https://gecici.email/en/email-verification-testing.html): Runnable Python fixture, real Chrome form, wrong-code rejection, verified state, replay rejection and cleanup. Hosted API simulation; no SMTP or LLM-agent test claimed. - [Türkçe doğrulama rehberi](https://gecici.email/yazilim-test-epostasi): Kendi test uygulamasında geçici kutudan form doğrulamasına kadar çalıştırılan akış. ## Practical guides — 14 November 2026 - [Guide index](https://gecici.email/en/guides.html): delivery troubleshooting, Playwright and Cursor workflows; [Turkish](https://gecici.email/rehberler.html). - [Playwright email verification](https://gecici.email/en/playwright-email-verification.html): tested Chromium + local Python form + hosted QA inbox. Message transport simulated, no external SMTP or model test. - [Cursor MCP connection](https://gecici.email/en/cursor-temporary-email-mcp.html): project configuration, token handling, tool errors and REST cleanup. Hosted API contract tested; Cursor desktop workflow not tested. - [Temporary email not receiving](https://gecici.email/en/temporary-email-not-receiving.html): distinguish sender rejection, expired inbox, delivery and extraction outcomes. ## First application verification task - Setup and steps: https://gecici.email/en/agents.html#first-task (TR: https://gecici.email/ai-ajanlar#first-task). - Reviewed-source download: https://gecici.email/examples/agent-first-task.py . Python3.9+ standard library. --run checks MCP extraction and independent local HTTP application acceptance; --serve lets a connected agent perform the task. - The fixture creates a QA-labelled inbox, inserts simulated mail, checks a one-use120second application challenge and deletes the inbox. Only fixed stage outcomes are printed. Tokens, addresses and codes stay in runtime memory. - --run is deterministic, not a model test. A supervised Codex connected-tool run passed17Nov2026; external SMTP, arbitrary signup, Claude/Cursor model completion and real adoption are not established. ## Installable Python client 1.2.0 - [Python SDK setup and API](https://gecici.email/downloads/python/README.md): core REST inbox lifecycle and hosted MCP matched verification. Direct wheel/source distribution; not published on PyPI. - Install with `python -m pip install -r https://gecici.email/downloads/python/requirements.txt` (wheel SHA256 pinned). Python 3.9+; tested with Python 3.12. - Token-redacted representations, bounded read/delete retries, explicit cleanup errors, ready/pending/ambiguous/blocked outcomes. Use `GeciciEmail(qa=True)` for your own tests. No acquired-user, external SMTP or framework compatibility claim. ## Node.js / TypeScript client 1.2.0 - [Node SDK setup and API](https://gecici.email/downloads/typescript/README.md): installable core client with TypeScript source/declarations; no runtime dependencies. Direct download, not an npm registry publication. - Install with `npm install https://gecici.email/downloads/typescript/gecici-email-1.2.0.tgz`; retain the generated lockfile. Node22+ metadata; tested on Node24. CommonJS, ESM named imports and a strict TypeScript consumer verified. - Matched verification, finite request/body deadlines, bounded read/delete retries and explicit cleanup errors. Inbox/result inspection and JSON serialization redact private values. Use `{ qa: true }` for own tests. No external SMTP, model completion or acquired-user claim.