REST API guide

Create an inbox

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.

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

• 403: the token is wrong, the inbox expired, or the custom name is reserved.
• 409: a custom name is already in use; choose another or generate a random inbox.
• 408 from OTP/links: no extracted value is available yet. Poll with a total deadline; do not treat other HTTP failures as waiting.
• MCP can return HTTP 200 with result.isError. Also inspect the tool content for timeout or found. Its wait tools accept 5–45 seconds.
• SSE sends data with a type field and closes after roughly 45 seconds. Native EventSource cannot attach a Bearer header; use an authenticated fetch stream or bounded polling.

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.

More examples

See the public English REST examples and downloadable client. The service is free for users and agents, but delivery time and external acceptance are not guaranteed.

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.