TEMP MAIL — disposable inboxes on @quangtb.com =========================================================================== Base URL : https://tmail.quangtb.com REST API : https://tmail.quangtb.com/api MCP : https://tmail.quangtb.com/mcp (Streamable HTTP, JSON-RPC over POST) Mail sent to @quangtb.com is accepted only if that mailbox exists and has not expired (default lifetime 10 minutes). Plus-addressing works: abc+github@quangtb.com is delivered to mailbox abc@quangtb.com. AUTH ---- Every endpoint except "/" and /api/health requires the API key, as ONE of: Authorization: Bearer X-API-Key: ?key= (handy, but ends up in logs/history) QUICK START (curl) ------------------ K="Authorization: Bearer " # 1. create a mailbox (random name, 10 minutes) curl -s -X POST -H "$K" https://tmail.quangtb.com/api/mailboxes -d '{}' # or a chosen name + 1 hour + note: curl -s -X POST -H "$K" https://tmail.quangtb.com/api/mailboxes \ -d '{"name":"shop-test","ttl":3600,"label":"signup on shop.example"}' # 2. wait for the next mail (long-poll, returns as soon as it arrives) curl -s -H "$K" "https://tmail.quangtb.com/api/mailboxes/shop-test@quangtb.com/wait?timeout=60" # 2b. or wait only for an OTP code curl -s -H "$K" "https://tmail.quangtb.com/api/mailboxes/shop-test@quangtb.com/otp?timeout=60" # 3. read the inbox / a message curl -s -H "$K" https://tmail.quangtb.com/api/mailboxes/shop-test@quangtb.com/messages curl -s -H "$K" https://tmail.quangtb.com/api/mailboxes/shop-test@quangtb.com/messages/latest ENDPOINTS --------- GET /api/health no auth GET /api/domains allowed domains + TTL limits GET /api/stats counts / storage POST /api/cleanup run the expiry cleanup now (cron does it every 5 min) POST /api/mailboxes create body: name? local part, a-z 0-9 . _ - (omit = random) length? random name length, 6-32 (default 10) domain? default = first allowed domain ttl? seconds, 60..604800 (default 600) label? free text webhook_url? POSTed on every new mail (see WEBHOOK) 409 if the name is taken by an active mailbox. GET /api/mailboxes list active mailboxes (?limit=100) GET /api/mailboxes/:address info PATCH /api/mailboxes/:address body: ttl? (expire ttl seconds FROM NOW), label?, webhook_url? DELETE /api/mailboxes/:address delete mailbox + its mail GET /api/mailboxes/:address/wait long-poll for a NEW message ?timeout=30 seconds, max 90 ?since= only messages with id > since; default = newest id at call time (i.e. truly new mail). since=0 returns an existing one. ?from= ?subject= case-insensitive substring filters ?otp=1 only messages where an OTP was detected -> {"timeout":false,"message":{...}} or {"timeout":true,"message":null} GET /api/mailboxes/:address/otp same params; -> {"otp":"123456", "message_id":..} GET /api/mailboxes/:address/messages summaries, newest first (?since=&limit=) DELETE /api/mailboxes/:address/messages empty the inbox GET /api/mailboxes/:address/messages/:id full message (:id or "latest"), marks seen DELETE /api/mailboxes/:address/messages/:id GET /api/mailboxes/:address/messages/:id/raw original .eml GET /api/mailboxes/:address/messages/:id/attachments/:index Message object: id, mailbox, to, from{name,address}, envelope_from, subject, otp, size, seen, received_at, text, html, headers[], links[{url,verify}], attachments[{filename,mime_type,size,download_url}], raw_url otp best-effort detection of a 4-8 digit / short alphanumeric code links all http(s) links; verify=true for ones that look like confirm/verify/magic-login/reset links Errors: {"error":"..."} with 400 / 401 / 404 / 409 / 500. WEBHOOK ------- If a mailbox has webhook_url, each new mail triggers: POST X-TempMail-Signature: sha256= {"event":"message.received","mailbox":"...","message":{summary incl. otp}} Secret = WEBHOOK_SECRET env (falls back to the API key). MCP --- Endpoint https://tmail.quangtb.com/mcp, same API key in the Authorization header. Claude Code: claude mcp add --transport http tempmail https://tmail.quangtb.com/mcp \ --header "Authorization: Bearer " Generic JSON config (Claude Desktop / Cursor / ...): { "mcpServers": { "tempmail": { "type": "http", "url": "https://tmail.quangtb.com/mcp", "headers": { "Authorization": "Bearer " } } } } Clients that can't send headers: https://tmail.quangtb.com/mcp?key= Tools: create_mailbox {name?, domain?, ttl_seconds?, label?, webhook_url?} list_mailboxes {limit?} extend_mailbox {address, ttl_seconds?, label?, webhook_url?} delete_mailbox {address} list_messages {address, since?, limit?} read_message {address, id? ("latest"), include_html?} wait_for_message {address, timeout_seconds? (<=60), since?, from?, subject?} wait_for_otp {address, timeout_seconds? (<=60), since?, from?, subject?} delete_message {address, id} Typical agent flow: create_mailbox -> fill the address into a signup form -> wait_for_otp -> type the code (or read_message -> open verify_links[0]). LIMITS ------ max message size MAX_MESSAGE_BYTES (default 10 MB; bigger mail is rejected) messages / mailbox MAX_MESSAGES_PER_MAILBOX (default 200) .eml + attachments kept only for mails <= 1.5 MB (D1 row limit); larger mails keep parsed text/html + attachment metadata receive only this service cannot send mail