Email Generator • REST API Reference

Developer API Reference

Automate end-to-end signup tests, transactional email checks, and domain MX validation in Playwright, Cypress, or CI pipelines using Email Generator JSON endpoints.

Base URLhttps://generatoremail.com
Admin / Key AuthX-API-Key: ak_...
Public Rate LimitPer-IP Sliding Window
Response Formatapplication/json
GET/api/public/domains

Retrieve the list of active disposable email domains available for public temporary mailbox generation.

Example Response
[
  {
    "name": "toraya.eu.cc",
    "active": true,
    "tier": "free",
    "source": "default"
  },
  {
    "name": "vapestore.eu.cc",
    "active": true,
    "tier": "free",
    "source": "default"
  }
]
POSTGET/api/public/mailbox

Instantly create and provision an active temporary email address. No authentication or API key is required on free public domains. You may request a custom username and domain, or omit them to auto-generate a fresh random address.

Example cURL (POST)
curl -X POST "https://generatoremail.com/api/public/mailbox" \
  -H "Content-Type: application/json" \
  -d '{"domain":"toraya.eu.cc","username":"qa_probe_01"}'
Example Response (200 OK)
{
  "success": true,
  "email": "qa_probe_01@toraya.eu.cc",
  "username": "qa_probe_01",
  "domain": "toraya.eu.cc",
  "inboxUrl": "https://generatoremail.com/toraya.eu.cc/qa_probe_01",
  "apiInboxUrl": "https://generatoremail.com/api/public/inbox?email=qa_probe_01%40toraya.eu.cc"
}
GET/api/public/inbox?email=user@domain

Poll incoming messages for an active temporary address on an approved platform domain. Reserved administrative local-parts (such as admin@, root@, or support@) are rejected with HTTP 403.

Example cURL
curl -s "https://generatoremail.com/api/public/inbox?email=qa_probe_01@toraya.eu.cc"
GET/api/tools/domain-check?domain=example.com

Public DNS MX and disposable email classification utility. Also available via our interactive Disposable Email Domain Checker.

Example Response
{
  "domain": "10minutemail.com",
  "isDisposable": true,
  "hasMx": true,
  "verdict": "Disposable / Temporary Email Domain",
  "riskScore": 95
}

Playwright & Node.js Automation Example

Use this clean snippet in your Playwright or Jest integration tests to generate a temporary email address, wait for the incoming OTP confirmation code, and finish sign-up verification automatically:

// test-signup-otp.ts
import { test, expect } from '@playwright/test';

test('Verify registration with Email Generator temporary inbox', async ({ page, request }) => {
  // 1. Instantly generate a temporary email address via REST API
  const mailRes = await request.post('https://generatoremail.com/api/public/mailbox', {
    data: { domain: 'toraya.eu.cc', username: `qa_run_${Date.now()}` }
  });
  const { email: testEmail } = await mailRes.json();

  // 2. Perform registration in your app UI
  await page.goto('https://yourapp.example.com/signup');
  await page.fill('input[type="email"]', testEmail);
  await page.click('button[type="submit"]');

  // 3. Poll Email Generator inbox for incoming OTP verification code
  let otpCode = '';
  for (let attempt = 0; attempt < 15; attempt++) {
    await page.waitForTimeout(2000);
    const inboxRes = await request.get(`https://generatoremail.com/api/public/inbox?email=${encodeURIComponent(testEmail)}`);
    const messages = await inboxRes.json();
    if (messages && messages.length > 0) {
      const body = messages[0].body || messages[0].subject || '';
      const match = body.match(/\b(\d{6})\b/);
      if (match) {
        otpCode = match[1];
        break;
      }
    }
  }

  expect(otpCode).not.toBe('');
  // 4. Enter received verification code
  await page.fill('input[name="otp"]', otpCode);
  await page.click('button[name="verify"]');
});

HTTP Status Codes & Response Handling

Status CodeMeaningAction Required
200 OKRequest succeeded. Returns JSON payload or message list.Parse response JSON.
400 Bad RequestMissing required query parameter (e.g. invalid or absent email).Validate input format before making API request.
403 ForbiddenAccess to administrative local-parts (admin@, support@) is restricted.Use standard random usernames for temporary testing.
429 Rate LimitSliding window request limit exceeded for your client IP address.Back off polling to 3-5 second intervals.
502 Gateway ErrorUnderlying mail backend provisioning timeout.Retry request after 2 seconds.

Embeddable Badges for GitHub READMEs & Test Suites

Integrating Email Generator into your open-source automated tests, Playwright, or Cypress test suites? Add an official badge to your repository README to show fast disposable test coverage.

API Integration BadgeEmail Generator API Badge
[![Email Generator API](https://generatoremail.com/badge.svg)](https://generatoremail.com)
Tested With BadgeTested with Email Generator Badge
[![Tested with Email Generator](https://generatoremail.com/badge-tested.svg)](https://generatoremail.com)

Attachment & Acceptable Use Policy

To prevent malware distribution, binary attachments are stripped from disposable mailboxes while plain-text and sanitized HTML bodies are returned via JSON. Automated API usage is subject to rate limits and our Terms of Service.

Developer REST API Documentation | Email Generator