TempMail API Documentation

{
  "success": true,
  "api_key": "mt_abc123xyz...",
  "message": "Save this key! It won't be shown again.",
  "usage": {
    "header": "X-API-Key: mt_abc123xyz...",
    "endpoints": [
      "GET /api/v1/generate",
      "POST /api/v1/generate",
      "GET /api/v1/inbox/:address",
      "GET /api/v1/extract-code/:address",
      "GET /api/v1/wait-code/:address"
    ]
  }
}

{
  "success": true,
  "email": "cool.fox123@mailtemp.web.id",
  "username": "cool.fox123",
  "expires_in": 3600,
  "created_at": 1718560000000
}

{
  "username": "myname"
}

{
  "success": true,
  "email": "cool.fox123@mailtemp.web.id",
  "messages": [
    {
      "id": "uuid-here",
      "address": "cool.fox123@mailtemp.web.id",
      "sender": "noreply@example.com",
      "subject": "Your verification code",
      "received_at": 1718560050000
    }
  ],
  "count": 1
}

{
  "success": true,
  "email": {
    "id": "uuid-here",
    "address": "cool.fox123@mailtemp.web.id",
    "sender": "noreply@example.com",
    "subject": "Your verification code",
    "body": "Your code is 483921",
    "html": "<p>Your code is <b>483921</b></p>",
    "received_at": 1718560050000
  }
}

{
  "success": true,
  "found": true,
  "codes": [
    {
      "email_id": "uuid-here",
      "sender": "noreply@example.com",
      "subject": "Your verification code",
      "codes": ["483921"],
      "received_at": 1718560050000
    }
  ],
  "checked_emails": 5
}

{
  "success": true,
  "found": true,
  "codes": [
    {
      "email_id": "uuid",
      "sender": "service@app.com",
      "subject": "Verify your account",
      "codes": ["582910"],
      "received_at": 1718560100000
    }
  ],
  "address": "myname@mailtemp.web.id",
  "since": 1718559900000,
  "checked_at": 1718560105000
}

const API_URL = "https://mailtemp-api.pay67514.workers.dev";
const API_KEY = "mt_your_api_key_here";

// Generate a temp email
async function generateEmail(customUsername) {
  const url = customUsername
    ? `${API_URL}/api/v1/generate`
    : `${API_URL}/api/v1/generate`;

  const options = {
    method: customUsername ? "POST" : "GET",
    headers: {
      "X-API-Key": API_KEY,
      "Content-Type": "application/json"
    }
  };

  if (customUsername) {
    options.body = JSON.stringify({ username: customUsername });
  }

  const res = await fetch(url, options);
  return await res.json();
}

// Get inbox
async function getInbox(email) {
  const res = await fetch(
    `${API_URL}/api/v1/inbox/${encodeURIComponent(email)}`,
    { headers: { "X-API-Key": API_KEY } }
  );
  return await res.json();
}

// Wait for verification code
async function waitForCode(email, timeoutSec = 30) {
  const since = Date.now();
  const maxAttempts = Math.ceil(timeoutSec / 5);

  for (let i = 0; i < maxAttempts; i++) {
    const res = await fetch(
      `${API_URL}/api/v1/wait-code/${encodeURIComponent(email)}?since=${since}`,
      { headers: { "X-API-Key": API_KEY } }
    );
    const data = await res.json();

    if (data.found && data.codes.length > 0) {
      return data.codes[0].codes[0]; // First code from first email
    }

    // Wait 5 seconds before retry
    await new Promise(r => setTimeout(r, 5000));
  }

  return null; // No code found
}

// === FULL EXAMPLE ===
async function main() {
  // 1. Generate email
  const { email } = await generateEmail("mybot.test");
  console.log("Temp email:", email);

  // 2. Use this email to register somewhere...
  console.log("Register with:", email);

  // 3. Wait for verification code
  console.log("Waiting for code...");
  const code = await waitForCode(email, 60);

  if (code) {
    console.log("Got verification code:", code);
  } else {
    console.log("No code received within timeout");
  }
}

main();

import requests
import time
import urllib.parse

API_URL = "https://mailtemp-api.pay67514.workers.dev"
API_KEY = "mt_your_api_key_here"

HEADERS = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}


def generate_email(username=None):
    """Generate a temporary email address."""
    if username:
        res = requests.post(
            f"{API_URL}/api/v1/generate",
            headers=HEADERS,
            json={"username": username}
        )
    else:
        res = requests.get(
            f"{API_URL}/api/v1/generate",
            headers=HEADERS
        )
    return res.json()


def get_inbox(email):
    """Get all emails in the inbox."""
    encoded = urllib.parse.quote(email)
    res = requests.get(
        f"{API_URL}/api/v1/inbox/{encoded}",
        headers=HEADERS
    )
    return res.json()


def extract_code(email):
    """Extract verification codes from emails."""
    encoded = urllib.parse.quote(email)
    res = requests.get(
        f"{API_URL}/api/v1/extract-code/{encoded}",
        headers=HEADERS
    )
    return res.json()


def wait_for_code(email, timeout=60, interval=5):
    """
    Wait for a verification code to arrive.
    Polls every `interval` seconds, up to `timeout` seconds.
    Returns the code string or None.
    """
    since = int(time.time() * 1000)
    elapsed = 0

    while elapsed < timeout:
        encoded = urllib.parse.quote(email)
        res = requests.get(
            f"{API_URL}/api/v1/wait-code/{encoded}?since={since}",
            headers=HEADERS
        )
        data = res.json()

        if data.get("found") and data.get("codes"):
            codes = data["codes"][0]["codes"]
            if codes:
                return codes[0]

        time.sleep(interval)
        elapsed += interval

    return None


# === FULL EXAMPLE ===
if __name__ == "__main__":
    # 1. Generate email (random or custom)
    result = generate_email("mybot.test")
    email = result["email"]
    print(f"Temp email: {email}")

    # 2. Use this email to register somewhere...
    print(f"Register with: {email}")

    # 3. Wait for verification code
    print("Waiting for verification code...")
    code = wait_for_code(email, timeout=60)

    if code:
        print(f"Got verification code: {code}")
    else:
        print("No code received within timeout")

pip install requests