API Documentation — TempMailAPI

STREAM GET /api/v1/stream

Server-Sent Events (SSE) persistent stream. Keeps a single, open persistent connection to our server and pushes incoming emails the exact millisecond they land on port 25. Zero refresh / Zero polling required.

✨

Smart Payload: Automatically extracts both code (for OTP number services like ChatGPT, WhatsApp) AND verification_link (for 1-click button services like Claude "Verify Now", Google, Twitter).

Query Parameters

Parameter	Type	Requirement	Description
email	string	Required	Target email address to listen on (e.g. `test@deiras.com`)
code	string	Required	Your personal API code (or Header `Authorization: Bearer YOUR_CODE`)
full	boolean	Optional	Default `false` (lean 1KB JSON). Pass `&full=true` if your bot specifically requires the raw HTML body inside the stream.

cURL Live Listen

curl -N "https://private.tempmailc.com/api/v1/stream?email=test@deiras.com&code=YOUR_API_CODE"

Event Payload Structure

event: message
data: {
  "event": "new_email",
  "email": "test@deiras.com",
  "code": "849201",                                      // Instant OTP digits (if sent)
  "verification_link": "https://claude.ai/magic-link?token=abc...", // Instant 1-click button (Claude "Verify Now", Google)
  "links": [
    "https://claude.ai/magic-link?token=abc..."
  ],
  "subject": "Sign in to Claude / Verification Code",
  "from": "noreply@anthropic.com",
  "text": "Click the link below to verify: https://claude.ai/magic-link...",
  "html_url": "https://private.tempmailc.com/api/v1/html?email=test@deiras.com&code=YOUR_API_CODE",
  "timestamp": 1790789400
}
        

POST /api/v1/webhook

Instant Webhook Notification (Push to Your Server). Whenever an email arrives on any of your assigned domains, our server dispatches an immediate HTTP POST with the JSON payload to your server endpoint.

💡

You can configure, test, and monitor your Webhook directly in the Dashboard Webhooks Tab, or manage it programmatically using the API below.

Webhook Management Endpoints

Method	Endpoint	Description
POST	/api/v1/webhook	Set or update your Webhook URL. Body: `{"webhook_url": "https://your-bot.com/wh"}`
GET	/api/v1/webhook	Check current Webhook URL, active status, and last 10 delivery latency logs.
POST	/api/v1/webhook/test	Send an instant test ping payload to your server and measure response latency in milliseconds.
DELETE	/api/v1/webhook	Remove your Webhook URL.

Python Webhook Receiver (FastAPI)

from fastapi import FastAPI, Request app = FastAPI() @app.post("/webhook") async def receive_email(request: Request): data = await request.json() # 1. OTP Code (if number code was sent like ChatGPT, WhatsApp) if data.get("code"): print(f"⚡ OTP Code: {data['code']}") # 2. 1-Click Verification Link (Claude 'Verify Now', Google, Twitter) elif data.get("verification_link"): print(f"🔗 Verify Link: {data['verification_link']}") return {"status": "ok"}

INFO Authentication

Every API request requires your personal API Code. You can provide it in any of the following ways:

Supported Authentication Methods

Method	Format	Example
Query Parameter	`?code=YOUR_CODE`	/api/v1/code?email=alice@deiras.com&code=YOUR_API_CODE
HTTP Header	`Authorization: Bearer YOUR_CODE`	Authorization: Bearer YOUR_API_CODE

GET /api/v1/code

High-speed in-memory OTP extractor. Returns the latest verification code digits found in the mailbox. Zero-cost deduplication: only consumes quota when a new code is delivered.

Query Parameters

Parameter	Type	Requirement	Description
email	string	Required	Target email address (e.g. `alice@deiras.com`)
code	string	Required	Your personal API code

Request Example

curl "https://private.tempmailc.com/api/v1/code?email=alice@deiras.com&code=YOUR_API_CODE"

Response Example

// When code arrives:
{"status": "ok", "code": "537281"}

// If no email received yet:
{"status": "empty", "code": ""}
        

GET /api/v1/inbox

Returns the full plain-text email message, including sender, subject, date, and body text.

Request Example

curl "https://private.tempmailc.com/api/v1/inbox?email=alice@deiras.com&code=YOUR_API_CODE"

Response Example

{
  "status": "ok",
  "email": "alice@deiras.com",
  "sender": "noreply@service.com",
  "subject": "Verify your account",
  "date": "Wed, 30 Sep 2026 18:30:00 +0000",
  "message": "Your verification code is: 537281"
}
        

GET /api/v1/html

Returns the complete graphical rendered HTML email. Ideal for rendering inside an iframe, taking screenshots, or extracting complex multi-part links.

Request Example

curl "https://private.tempmailc.com/api/v1/html?email=alice@deiras.com&code=YOUR_API_CODE"

Response Example

{
  "status": "ok",
  "html": "<html><body><h1>Welcome!</h1><a href='https://...'>Verify Now</a></body></html>"
}
        

GET /api/v1/domains

Returns the array of active domains assigned to your account. You can create unlimited random usernames on any of these domains.

Request Example

curl "https://private.tempmailc.com/api/v1/domains?code=YOUR_API_CODE"

Response Example

{
  "ok": true,
  "domains": [
    "deiras.com",
    "yourdomain2.com"
  ]
}
        

🤖 PROTOCOL Kopeechka 2.0 High-Speed API

Full Kopeechka 2.0 Protocol Compatibility (<50ms Response). Designed for high-volume automated scripts, ZennoPoster, Browser Automation Studio (BAS), and custom bot automation. Use your API token directly with standard Kopeechka clients.

Authentication & Base URL

Parameter	Type	Description
Base URL	URL	`https://private.tempmailc.com`
token	string	Your personal API token (e.g. `YOUR_API_CODE`). Passed via URL query `?token=...` or header `Authorization: Bearer ...`

Kopeechka 2.0 Endpoints

Method	Endpoint	Description	Example
GET	/mailbox-get-email	Order new mailbox with realistic human name	`/mailbox-get-email?site=telegram&token=YOUR_API_CODE`
GET	/mailbox-get-message	Poll for OTP code or full message	`/mailbox-get-message?id=TASK_ID&token=YOUR_API_CODE&full=1`
GET	/mailbox-cancel	Cancel mailbox and release task	`/mailbox-cancel?id=TASK_ID&token=YOUR_API_CODE`
GET	/user-balance	Check remaining requests quota & balance	`/user-balance?token=YOUR_API_CODE`
GET	/mailbox-get-domains	List private domains assigned to your account	`/mailbox-get-domains?token=YOUR_API_CODE`
GET	/mailbox-zones	List available domain zones	`/mailbox-zones?token=YOUR_API_CODE`

Python Automation Example (requests)

import requests, time

BASE = "https://private.tempmailc.com"
TOKEN = "YOUR_API_CODE"

# 1. Order a dedicated email address
order = requests.get(f"{BASE}/mailbox-get-email", params={"site": "telegram", "token": TOKEN}).json()
task_id = order["id"]
email = order["mail"]
print(f"Ordered: {email} (Task: {task_id})")

# 2. Poll for verification code
for _ in range(30):
    res = requests.get(f"{BASE}/mailbox-get-message", params={"id": task_id, "token": TOKEN, "full": 1}).json()
    if res.get("status") == "OK":
        print(f"Verification Code: {res['value']}")
        break
    time.sleep(2)

cURL Quick Test

curl "https://private.tempmailc.com/mailbox-get-email?site=telegram&token=YOUR_API_CODE"

⚡ PERFORMANCE Zero-Cost Deduplication & Quotas

Our gateway runs in-memory Redis deduplication. Repeated polling requests while waiting for an incoming email do NOT consume your plan quota.

✨

1 Request per New Email: You are only billed 1 request when a brand new code or message arrives.
Recommended Frequency: For REST APIs, poll every 2–3 seconds. For zero polling overhead, use SSE Live Stream.
Daily Reset: Daily limits reset automatically every night at 00:00 UTC.

⚠️ REFERENCE HTTP Status & Error Codes

Standard HTTP status codes and error JSON payloads returned when an issue occurs:

Status	Error Code	Meaning & Solution
`403`	invalid_trial_code	Your personal API code is missing, invalid, or expired.
`403`	domain_not_allowed	The requested domain is not assigned to your account.
`403`	limit_reached	You reached your request quota. Resets at 00:00 UTC or upon top-up.
`403`	subscription_expired	Your subscription has expired. Please renew in Billing.
`400`	invalid_email	The email parameter is missing or does not contain an '@' sign.

Developer API Documentation