← gecici.email

Free temporary email API

Create a disposable inbox in one HTTP request and receive email programmatically. No signup, credit card, global API key or server installation is required. Each inbox starts with 60 minutes and returns a private token for reading and deleting its messages.

Use it for your application's email tests and short-lived AI agent workflows. The service receives email; it does not send replies or provide a permanent mailbox.

Create your first disposable inbox

Base URL: https://gecici.email/api/v1. An agent with HTTPS access can call this endpoint directly. No SSH session, local mail server or MCP client is necessary for REST access.

curl --fail-with-body --silent --show-error --max-time 15 \
  https://gecici.email/api/v1/inbox/generate \
  -H 'Content-Type: application/json' \
  -H 'X-Gecici-Client: qa-test' \
  --data '{}'

This example labels the inbox as a test. The JSON response contains success: true and an inbox object:

inbox.address
The recipient address to pass to your application's email sender.
inbox.token
The secret returned at creation. Keep it in private runtime memory; do not send it to the application or save the response in logs.
inbox.createdAt / inbox.expiresAt
Unix timestamps in milliseconds. Use the creation time to match a new verification attempt.
inbox.ttlSeconds
The starting lifetime: 3600 seconds.
  1. Send your application's test email to inbox.address.
  2. URL-encode that address as a path segment, then call GET /inbox/{address}/messages with Authorization: Bearer <inbox.token>. Read the response's messages array. An empty array means no message is available yet.
  3. When finished, call DELETE /inbox/{address} with the same token and check the response. Keep polling and retries bounded.

Inbox creation does not prove that mail arrived. A timeout during creation may still have created an inbox; do not automatically repeat the POST. For a ready-to-run simulated check with cleanup, use the existing Python QA example.

Connect Python, Node.js or an MCP agent

Python 3.9+

Use a virtual environment. The requirements file pins the downloadable wheel's SHA256 hash:

python -m pip install -r https://gecici.email/downloads/python/requirements.txt

Python first workflow, matching filters and cleanup

Node.js 22+ / TypeScript

npm install https://gecici.email/downloads/typescript/gecici-email-1.2.0.tgz

Node first workflow, TypeScript types and cleanup. Keep the generated lockfile. Both clients are version 1.2.0, distributed directly from this site; these are not PyPI or npm registry listings.

Remote MCP

Connect https://gecici.email/mcp to a compatible HTTP MCP client. The agent setup guide includes Claude Code and Cursor configurations and a first verification task. No global API key is required; each inbox still requires its own token.

Create an inbox: endpoint reference

POST /inbox/generate
Content-Type: application/json

{}

POST /inbox/custom
Content-Type: application/json

{"prefix":"qa-flow-42"}

A custom prefix must be 4–32 ASCII characters, contain a digit and an internal -, _, or ., and not be a reserved role name.

Read an inbox

GET /inbox/{address}
GET /inbox/{address}/messages
GET /inbox/{address}/otp
GET /inbox/{address}/links
Authorization: Bearer <token>

The OTP and link endpoints return extracted values when available; they never visit an external link. The OTP and link endpoints return HTTP 408 when no extracted value is available; they do not wait for a future message. Poll at bounded intervals with a total deadline. Other HTTP errors must be handled separately. An empty result is not proof that a message was delivered. Encode the address as a URL path segment.

Extract a verification code or link for a specific attempt

For a new verification flow, prefer gecici_wait_for_verification through hosted MCP or either SDK's matched-verification method. Supply the inbox address, its token and since=inbox.createdAt, then match your application's sender and subject. HTTPS links also require your application's exact expected_link_host.

The tool returns ready, pending, ambiguous or blocked. Only ready includes the extracted value. It does not open a link or submit a code: your application must confirm acceptance. An HTTP or tool error is not a pending message.

Manage an inbox

POST /inbox/{address}/extend
Authorization: Bearer <token>
Content-Type: application/json

{"minutes":30}

DELETE /inbox/{address}
Authorization: Bearer <token>

Deletion removes logical database records; it is not a guarantee of irreversible erasure from disk pages, backups, or infrastructure logs.

Test a complete REST and MCP workflow with Python

The qa-flow.py example uses only the Python 3 standard library. Download and review the source, then run it:

python3 qa-flow.py --run
  1. Create one disposable inbox and keep its token in memory.
  2. Verify that a wrong token is rejected with HTTP 403.
  3. Add a fictional verification message to that same inbox through the simulation endpoint.
  4. Read the extracted code with REST and the message with MCP.
  5. Delete the created inbox in a finally block, including when a test fails.

A passing result has created, wrong_token_denied, rest_otp_matched, mcp_message_read and cleanup set to true. The script prints no address, token, message content or code. The X-Gecici-Client: qa-test header separates these operations from normal usage counts.

This tests authentication, simulation, extraction and MCP reading. It does not test external SMTP delivery: external_smtp_tested stays false. For your own application's delivery test, replace the simulation step with mail sent by your authorized test application. This workflow was checked against our own disposable inbox on October 25, 2026.

Troubleshooting

Remote MCP connection and tool guide →

To add inbox tools to your browser agent, follow the tested browser-use Python example and its result explanations.

Price, lifetime and service limits

The hosted inbox, core REST API and MCP tools are free to use. Free access does not mean unlimited capacity or an SLA. Inboxes start with 60 minutes; the token holder can extend or delete an active inbox. This is a receive-only service: no outbound email, permanent identity, team accounts or durable webhook delivery.

External senders may reject temporary domains or delay delivery. Use a permanent email address for sensitive accounts and account recovery. Read the storage and retention policy before integrating. See the public English REST examples for additional requests.

Test a complete verification form

The owned-application verification guide includes a runnable Python fixture, real Chrome checks, incorrect-code and replay controls, and cleanup.

Practical setup and troubleshooting guides

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