📡 API Documentation

Integrate Phantom Mail into your apps. Generate disposable emails and read messages programmatically.

Getting Started Authentication Rate Limits Endpoints — POST /api/v1/generate — GET /api/v1/emails Error Codes Code Examples

Getting Started

Premium Feature: API access requires a Phantom Mail Premium account. Sign in on the main site, go to the Premium Dashboard → API Key tab, and generate your key.

Base URL https://mail.unknowns.app

All API endpoints are served over HTTPS. Requests must include your API key in the X-API-Key header.

Authentication

Include your API key in every request using the X-API-Key HTTP header.

HTTP Header

X-API-Key: pm_your32characterapikey...

⚠️ Keep your API key secret. Never expose it in client-side code or public repositories. If compromised, regenerate it from your dashboard immediately.

Rate Limits

Rate limits are applied per API key, per day (UTC reset at midnight).

Plan

Requests / Day

Notes

⭐ Premium

10,000

High-volume use

When you exceed the rate limit, you'll receive a 429 response with X-RateLimit-Limit and X-RateLimit-Remaining info in the response body.

Endpoints

POST /api/v1/generate Generate a temporary email address

🔑 Requires API Key

Generates a new disposable email address. Optionally specify a custom username (Premium only). The address expires in 1 hour by default.

Request Headers

Header	Type	Required	Description
X-API-Key	string	Required	Your Premium API key

Request Body (JSON, optional)

Field	Type	Required	Description
username	string	Optional	Custom username (3–30 chars, a-z 0-9 . _ -). Generates `{username}@unknownlll2829.qzz.io`. Premium only.

Responses

200 OK — Email generated successfully

JSON

{
  "success": true,
  "email": "cooluser42@unknownlll2829.qzz.io",
  "expiresIn": 3600,
  "usage": {
    "today": 5,
    "limit": 10000
  }
}

400 Bad Request — Invalid username

JSON

{ "error": "Username must be 3-30 characters" }

429 Too Many Requests — Rate limit exceeded

JSON

{ "error": "Rate limit exceeded", "limit": 10000, "used": 10000 }

GET /api/v1/emails Retrieve emails for an address

🔑 Requires API Key

Returns all received emails for a given address. The address must exist (previously generated via the API or the web interface).

Query Parameters

Parameter	Type	Required	Description
address	string	Required	The full email address to check (e.g. `user@unknownlll2829.qzz.io`)

Responses

200 OK

JSON

{
  "success": true,
  "address": "cooluser42@unknownlll2829.qzz.io",
  "count": 2,
  "emails": [
    {
      "id": "abc123",
      "from": "noreply@example.com",
      "subject": "Your verification code",
      "body": "Your code is 123456",
      "hasHtml": true,
      "timestamp": 1710000000000
    }
  ]
}

404 Not Found — Email address not found or expired

JSON

{ "error": "Email not found or expired" }

Error Codes

Status	Code	Description
401	Unauthorized	API key missing or invalid
400	Bad Request	Missing or invalid parameters
403	Forbidden	Feature requires Premium plan
404	Not Found	Resource does not exist or has expired
429	Too Many Requests	Daily rate limit exceeded
500	Server Error	Internal server error — try again

Code Examples

Quick start examples in popular languages.

Generate an email address (JavaScript)

JavaScript (fetch)

const response = await fetch('https://mail.unknowns.app/api/v1/generate', {
  method: 'POST',
  headers: {
    'X-API-Key': 'pm_your_api_key_here',
    'Content-Type': 'application/json'
  },
  // Optional: provide a custom username
  body: JSON.stringify({ username: 'myapp_test' })
});

const data = await response.json();
console.log(data.email); // myapp_test@unknownlll2829.qzz.io

Check for new emails (JavaScript)

JavaScript (fetch)

const emailAddr = 'myapp_test@unknownlll2829.qzz.io';

const res = await fetch(
  `https://mail.unknowns.app/api/v1/emails?address=${encodeURIComponent(emailAddr)}`,
  { headers: { 'X-API-Key': 'pm_your_api_key_here' } }
);

const data = await res.json();
console.log(`${data.count} email(s) received`);
data.emails.forEach(email => {
  console.log(`From: ${email.from} | Subject: ${email.subject}`);
});

Python example

Python (requests)

import requests

API_KEY = "pm_your_api_key_here"
BASE = "https://mail.unknowns.app/api/v1"
HEADERS = {"X-API-Key": API_KEY}

# Generate email
r = requests.post(f"{BASE}/generate", headers=HEADERS)
email = r.json()["email"]
print(f"Email: {email}")

# Poll for messages
r = requests.get(f"{BASE}/emails", headers=HEADERS, params={"address": email})
msgs = r.json().get("emails", [])
for msg in msgs:
    print(f"From: {msg['from']} | {msg['subject']}")

cURL example

cURL

# Generate a random email
curl -X POST https://mail.unknowns.app/api/v1/generate \
  -H "X-API-Key: pm_your_api_key_here"

# Check inbox
curl https://mail.unknowns.app/api/v1/emails?address=user@unknownlll2829.qzz.io \
  -H "X-API-Key: pm_your_api_key_here"

Need help? Contact us on Telegram @unknownlll2829

📡 API Documentation

Contents