Developer Docs & API
v1.0 API Documentation & Integration Guide

TempEmailfree Documentation

Complete technical reference for generating anonymous disposable mailboxes, capturing incoming verification emails, extracting OTP security codes in real-time, and automating end-to-end user registration flows.

Architecture & Design

How TempEmailfree Works Under the Hood

TempEmailfree provides real-time, disposable, ephemeral mailboxes without requiring accounts, phone numbers, or passwords. Incoming emails are processed by high-performance mail exchangers (MX servers) and relayed through our ultra-low latency proxy layer.

01

Zero Configuration

Instantly provision an email address with random or user-chosen prefixes. No database signups.

02

Real-Time Polling

Poll emails with sub-second latency. Inboxes refresh automatically every 4 to 8 seconds.

03

Automated Shredding

Emails and sessions are ephemeral. All message contents are purged to maintain 100% privacy.

Developer Quick Start

Provision a Disposable Mailbox in 3 Steps

Whether you are testing a signup flow locally or running automated continuous integration (CI) pipelines, you can interact with our endpoints in standard JSON:

  1. 1
    Fetch active domains: Call GET /api/mail?endpoint=domains to pick an active domain suffix.
  2. 2
    Register account & token: Submit your chosen address to POST /api/mail?endpoint=accounts then request an auth token via POST /api/mail?endpoint=token.
  3. 3
    Poll messages & extract code: Query GET /api/mail?endpoint=messages with your bearer token to read incoming verification messages.
Core Innovations

Smart OTP Extraction & One-Click Link Verification

Unlike legacy temporary mail services that force you to open confusing HTML emails and scroll through promotional banners, TempEmailfree uses an intelligent client-side parsing engine:

Automated OTP Detector

Extracts 4 to 8 digit numeric and alphanumeric 2FA codes directly from email headers and bodies. Provides a one-tap copy button with instant feedback.

Pattern: /(?:code|otp|verify)[\s\S]*?\b(\d{4,8})\b/i
One-Click Verification Links

Scans for activation links (such as confirm email, activate account, or verify identity) and highlights a direct action button so users never miss confirmation tokens.

Target: a[href*='verify'], a[href*='confirm']
REST API Specification

Endpoints & Code Playground

GET/api/mail?endpoint=domains
curl -s "https://tempemail.evostackr.in/api/mail?endpoint=domains"
POST/api/mail?endpoint=accounts
curl -X POST "https://tempemail.evostackr.in/api/mail?endpoint=accounts" \
  -H "Content-Type: application/json" \
  -d '{"address": "developer_test_01@guerrillamailblock.com", "password": "SecureTestPassword123!"}'
GET/api/mail?endpoint=messages
curl -s "https://tempemail.evostackr.in/api/mail?endpoint=messages" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN_HERE"
End-to-End Automation

Automating Signups with Playwright or Cypress

Stop burning real corporate email addresses and risking IP bans during automated test runs. Use this drop-in Playwright script to verify email signups in your CI/CD pipelines:

tests/signup-with-otp.spec.ts
import { test, expect } from "@playwright/test";

test("Automate user signup with disposable email & instant OTP", async ({ page }) => {
  const BASE_API = "https://tempemail.evostackr.in/api/mail";
  
  // 1. Get domain and create disposable mailbox
  const domRes = await fetch(`${BASE_API}?endpoint=domains`);
  const { "hydra:member": domains } = await domRes.json();
  const domain = domains[0].domain;
  
  const testEmail = `qa_auto_${Date.now()}@${domain}`;
  const password = "AutomatedSecurePassword123!";
  
  await fetch(`${BASE_API}?endpoint=accounts`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ address: testEmail, password }),
  });

  const tokenRes = await fetch(`${BASE_API}?endpoint=token`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ address: testEmail, password }),
  });
  const { token } = await tokenRes.json();

  // 2. Perform signup on target website
  await page.goto("https://your-service.com/signup");
  await page.fill('input[name="email"]', testEmail);
  await page.fill('input[name="password"]', "UserSecretPass!99");
  await page.click('button[type="submit"]');

  // 3. Poll TempEmailfree API for verification OTP
  let otpCode = null;
  for (let attempt = 0; attempt < 12; attempt++) {
    await new Promise((r) => setTimeout(r, 2500));
    const inboxRes = await fetch(`${BASE_API}?endpoint=messages`, {
      headers: { Authorization: `Bearer ${token}` },
    });
    const inbox = await inboxRes.json();
    if (inbox["hydra:member"]?.length > 0) {
      const msgId = inbox["hydra:member"][0].id;
      const detailRes = await fetch(`${BASE_API}?endpoint=messages/${msgId}`, {
        headers: { Authorization: `Bearer ${token}` },
      });
      const detail = await detailRes.json();
      const match = (detail.text || "").match(/\b\d{4,8}\b/);
      if (match) {
        otpCode = match[0];
        break;
      }
    }
  }

  expect(otpCode).not.toBeNull();
  console.log(`Successfully received OTP: ${otpCode}`);

  // 4. Input verification code into UI
  await page.fill('input[name="otp"]', otpCode);
  await page.click('button#verify-btn');
  await expect(page.locator("text=Welcome to your dashboard")).toBeVisible();
});
Privacy & Security Compliance

Data Handling & Ephemeral Lifecycle

Zero Logging & Tracking:We do not log visitor IP addresses, read your emails, or sell behavioral data to third-party ad brokers.
Automatic Expiration:Messages and temporary addresses automatically expire. Emails are permanently shredded from memory.
Important Usage Advisory:Because disposable addresses expire, do not use TempEmailfree for critical accounts, banking, legal documents, or permanent services.
Developer Questions

Frequently Asked Questions

Can I send outbound emails using the API?

No. TempEmailfree is an inbound-only disposable receiver designed to protect users from spam. Outbound sending is disabled to prevent abusive email activity and protect domain reputation.

How fast do emails arrive in the temporary inbox?

Most verification emails and OTP codes arrive in less than 2 to 5 seconds depending on the sender's SMTP relay servers. Our web client polls every few seconds to display incoming messages in real-time.

Is there any rate limiting on the API proxy?

Our public gateway supports reasonable automated QA testing. For extreme high-volume concurrent loads (>100 requests per second), consider throttling requests or self-hosting upstream workers.