API Documentation

🔑 Authentication

All API endpoints (under /api/*) require an API key passed in the request header.

Required Header

Header	Value	Description
x-api-key	string	Your API key starting with `tmp_`. Get it from your Dashboard.

// Example with fetch (Node.js / Browser)
const HEADERS = {
  'x-api-key': 'tmp_your_api_key_here',
  'Content-Type': 'application/json'
};

const res = await fetch('https://tempmail-worker.hasildia1.workers.dev/api/generate', {
  method: 'POST',
  headers: HEADERS
});

⚠️ Error Handling

All responses follow a consistent JSON format. Check the success field first.

✅ Success

{
  "success": true,
  "data": { ... },
  "ts": "2026-04-27T14:00:00.000Z"
}

❌ Error

{
  "success": false,
  "error": "Error description",
  "ts": "2026-04-27T14:00:00.000Z"
}

HTTP Status Codes

Code	Meaning
200	Success
400	Bad request — invalid parameters
401	Unauthorized — missing or invalid API key
404	Not found — resource does not exist
429	Too many requests — rate limit hit (public endpoints only)
503	No domains available for this account

POST /api/generate

Generate a new random temporary email address. The returned address is immediately ready to receive emails. Domain selection respects your account's domain access (public + any private domains assigned to you).

🔑 Requires x-api-key header

Request Body

Parameter	Type	Required	Description
No request body required — send empty POST request.

Response Fields

Field	Type	Description
email	string	Full email address, e.g. `james47@domain.com`
domain	string	The domain part of the email
username	string	The local part (before @)
expires_in_hours	number	TTL in hours (default: 6)

200 — Success

{
  "success": true,
  "data": {
    "email": "james47@mail.example.com",
    "domain": "mail.example.com",
    "username": "james47",
    "expires_in_hours": 6
  },
  "ts": "2026-04-27T14:00:00.000Z"
}

⚡ Try It Live

Your API Key

GET /api/inbox/:address

Retrieve all emails currently in the inbox for the given email address. Returns up to 50 most recent emails, sorted by newest first.

🔑 Requires x-api-key header

URL Parameters

Parameter	Type	Required	Description
address	string	Required	Full email address (URL-encoded). Example: `james47%40mail.example.com`

Response Fields

Field	Type	Description
address	string	The queried email address
count	number	Number of emails found
emails	array	List of email objects (see below)
emails[].id	uuid	Unique email ID — use for fetching full content
emails[].from_address	string	Sender email address
emails[].subject	string	Email subject line
emails[].created_at	datetime	When the email was received (ISO 8601)
emails[].expires_at	datetime	When the email will be auto-deleted
emails[].text_content	string	Plain-text body (first 5000 chars)

// Poll inbox every 2 seconds
async function waitForEmail(address, apiKey, timeoutMs = 120000) {
  const start = Date.now();

  while (Date.now() - start < timeoutMs) {
    const res  = await fetch(
      `https://tempmail-worker.hasildia1.workers.dev/api/inbox/${encodeURIComponent(address)}`,
      { headers: { 'x-api-key': apiKey } }
    );
    const json = await res.json();

    if (json.data.emails.length > 0) {
      return json.data.emails[0]; // Return first email
    }

    await new Promise(r => setTimeout(r, 2000)); // Wait 2s
  }

  throw new Error('Timeout: no email received in ' + timeoutMs + 'ms');
}

DELETE /api/inbox/:address

Delete all emails in the inbox for the given address. Useful for cleanup after processing OTP codes or verification links.

🔑 Requires x-api-key header

URL Parameters

Parameter	Type	Required	Description
address	string	Required	Full email address (URL-encoded)

200 — Success

{
  "success": true,
  "data": { "cleared": true, "address": "james47@mail.example.com" },
  "ts": "2026-04-27T14:00:00.000Z"
}

GET /api/email/:id

Retrieve the full content of a specific email by its ID. Returns both plain-text and HTML content if available.

🔑 Requires x-api-key header

URL Parameters

Parameter	Type	Required	Description
id	uuid	Required	Email UUID from the inbox list

Response Fields

Field	Type	Description
id	uuid	Unique email identifier
from_address	string	Sender email address
to_address	string	Recipient email address
subject	string	Email subject line
text_content	string	Plain-text body (max 5000 chars)
html_content	string	HTML body (max 50,000 chars, null if none)
size_bytes	number	Raw email size in bytes
created_at	datetime	When the email arrived
expires_at	datetime	Auto-deletion time

// Get full email content (commonly used for OTP extraction)
const res  = await fetch(
  `https://tempmail-worker.hasildia1.workers.dev/api/email/${emailId}`,
  { headers: { 'x-api-key': 'tmp_your_api_key' } }
);
const json = await res.json();

const text = json.data.text_content; // Plain text
const html = json.data.html_content; // HTML (may be null)

// Extract OTP with regex
const otpMatch = text.match(/\b\d{6}\b/);
const otp = otpMatch ? otpMatch[0] : null;
console.log('OTP:', otp);

DELETE /api/email/:id

Delete a single email by its ID.

🔑 Requires x-api-key header

URL Parameters

Parameter	Type	Required	Description
id	uuid	Required	Email UUID to delete

200 — Success

{ "success": true, "data": { "deleted": true }, "ts": "..." }

GET /api/domains

List all email domains available to your account. Returns public domains plus any private domains your account has been granted access to by the admin.

🔑 Requires x-api-key header

Response Fields

Field	Type	Description
domains	array	List of domain objects
domains[].domain	string	Domain name, e.g. `mail.example.com`

200 — Success

{
  "success": true,
  "data": {
    "domains": [
      { "domain": "mail.example.com" },
      { "domain": "inbox.example.net" }
    ]
  },
  "ts": "2026-04-27T14:00:00.000Z"
}

GET /health

Check if the API service is running. No authentication required. Useful for uptime monitoring.

✅ No authentication required

200 — Success

{
  "success": true,
  "data": {
    "status": "ok",
    "service": "TempMail",
    "version": "1.0.0"
  },
  "ts": "2026-04-27T14:00:00.000Z"
}

GET /api/otp/:address 🤖 ChatGPT Ready

Scan the inbox of :address and automatically extract a 6-digit OTP code. Optimized for OpenAI / ChatGPT verification emails — prioritizes emails from @openai.com, noreply@, and subjects containing words like "verification", "chatgpt", "login code".

🔑 Requires x-api-key header

URL Parameters

Parameter	Type	Required	Description
address	string	Required	Full email address (URL-encoded). Example: `james47%40mail.example.com`

OTP Detection Priority (auto, no config needed)

#	Source	Pattern
1	Email Subject	your chatgpt code is XXXXXX
2	Plain Text Body	verification code ... XXXXXX
3	HTML Body	<h1>XXXXXX</h1>, <td>XXXXXX</td>
4	Fallback	Any 6-digit number in text body

Response Fields

Field	Type	Description
found	boolean	Whether an OTP code was found
otp	string \| null	The 6-digit OTP code, or `null` if not found yet — keep polling
email_id	uuid	ID of the email that contained the OTP
from	string	Sender address (e.g. `noreply@openai.com`)
subject	string	Email subject line
received_at	datetime	When the OTP email arrived
message	string	Human-readable status (when `found: false`)

✅ OTP Found

{
  "success": true,
  "data": {
    "found": true,
    "otp": "847291",
    "email_id": "uuid-...",
    "from": "noreply@openai.com",
    "subject": "Your ChatGPT login code",
    "received_at": "2026-04-27T14:00:05Z"
  }
}

⏳ Not Yet

{
  "success": true,
  "data": {
    "found": false,
    "otp": null,
    "message": "No OTP code found in any inbox emails"
  }
}

// Poll OTP every 2 seconds (same interval as old bot)
async function waitForOtp(email, apiKey, timeoutMs = 120000) {
  const HDR      = { 'x-api-key': apiKey };
  const deadline = Date.now() + timeoutMs;

  while (Date.now() < deadline) {
    const res  = await fetch(
      `https://tempmail-worker.hasildia1.workers.dev/api/otp/${encodeURIComponent(email)}`,
      { headers: HDR }
    );
    const json = await res.json();

    if (json.data.found) {
      console.log('OTP:', json.data.otp);       // e.g. "847291"
      console.log('From:', json.data.from);     // "noreply@openai.com"
      return json.data.otp;
    }

    await new Promise(r => setTimeout(r, 2000)); // Poll every 2s
  }

  throw new Error('OTP not received within ' + (timeoutMs / 1000) + 's timeout');
}

📦 Complete Node.js Example

Full workflow: generate email → wait for OTP → extract code.

const API = 'https://tempmail-worker.hasildia1.workers.dev';
const HDR = { 'x-api-key': 'tmp_your_key' };

async function main() {
  // 1. Generate temp email
  const { email } = (await (await fetch(`${API}/api/generate`, { method: 'POST', headers: HDR })).json()).data;
  console.log('Email:', email);

  // 2. ... trigger ChatGPT signup with this email ...

  // 3. Poll OTP (auto-detects ChatGPT / OpenAI emails)
  const otp = await waitForOtp(email);
  console.log('OTP:', otp); // e.g. "847291"

  // 4. ... submit otp to OpenAI ...
}

async function waitForOtp(email, timeout = 120000) {
  const deadline = Date.now() + timeout;
  while (Date.now() < deadline) {
    const json = await (await fetch(`${API}/api/otp/${encodeURIComponent(email)}`, { headers: HDR })).json();
    if (json.data.found) return json.data.otp;
    await new Promise(r => setTimeout(r, 2000));
  }
  throw new Error('OTP timeout');
}

main().catch(console.error);

TempMail API Reference

🔑 Authentication

⚠️ Error Handling

📦 Complete Node.js Example