📧 TempMail API Documentation

RESTful API for Temporary Email Service

📑 Table of Contents

🌐 Base URL

https://yourdomain.com/api.php

All API requests are made to this base URL. The API returns JSON responses for all endpoints.

✨ Generate Email

GET /generate

Generate a new temporary email address. Can generate random or custom username.

Parameters

Parameter Type Required Description
username string Optional Custom username (3-20 alphanumeric characters). If not provided, random username will be generated.
⚠️ Note: Reserved usernames like admin, info, administrator, etc. are blocked and cannot be used.

Reserved Usernames

admin
administrator
root
system
info
contact
support
help
webmaster
postmaster
noreply
abuse
security
and more...

Example Request - Random

GET /api.php/generate

Example Request - Custom

GET /api.php/generate?username=johnsmith

Success Response

{
  "success": true,
  "email": "johnsmith@yourdomain.com",
  "username": "johnsmith",
  "domain": "yourdomain.com",
  "expires_at": "2026-01-25 14:30:00"
}

Error Response - Invalid Username

{
  "success": false,
  "error": "Invalid username. Use 3-20 alphanumeric characters only."
}

Error Response - Reserved Username

{
  "success": false,
  "error": "This username is reserved and cannot be used."
}

Error Response - Username Taken

{
  "success": false,
  "error": "Username already taken. Please choose another one."
}

📬 Get Inbox

GET /inbox/{email}

Retrieve all emails for a specific temporary email address.

URL Parameters

Parameter Type Required Description
email string Required The full email address (can be URL encoded)

Example Request

GET /api.php/inbox/johnsmith@yourdomain.com

Success Response

{
  "success": true,
  "email": "johnsmith@yourdomain.com",
  "created_at": "2026-01-24 14:30:00",
  "expires_at": "2026-01-25 14:30:00",
  "total": 2,
  "emails": [
    {
      "id": 1,
      "from_email": "sender@example.com",
      "from_name": "John Doe",
      "subject": "Welcome!",
      "is_read": 0,
      "received_at": "2026-01-24 14:35:00"
    },
    {
      "id": 2,
      "from_email": "noreply@service.com",
      "from_name": "Service",
      "subject": "Verify your email",
      "is_read": 1,
      "received_at": "2026-01-24 14:40:00"
    }
  ]
}

Error Response

{
  "error": "Email not found",
  "searched_for": "test@yourdomain.com",
  "hint": "Generate this email first via /generate endpoint"
}

📧 Get Email Detail

GET /email/{id}

Retrieve full details of a specific email, including body content and attachments.

URL Parameters

Parameter Type Required Description
id integer Required The email ID
📌 Note: This endpoint automatically marks the email as read.

Example Request

GET /api.php/email/1

Success Response

{
  "success": true,
  "email": {
    "id": 1,
    "email_address_id": 1,
    "from_email": "sender@example.com",
    "from_name": "John Doe",
    "subject": "Welcome!",
    "body_text": "Hello, welcome to our service!",
    "body_html": "<h1>Welcome!</h1><p>Hello, welcome to our service!</p>",
    "is_read": 1,
    "received_at": "2026-01-24 14:35:00"
  },
  "attachments": [
    {
      "id": 1,
      "filename": "document.pdf",
      "size": 102400,
      "content_type": "application/pdf",
      "file_path": "/uploads/attachments/document.pdf"
    }
  ]
}

Error Response

{
  "error": "Email not found"
}

🗑️ Delete Email

DELETE /email/{id}

Delete a specific email from the inbox.

URL Parameters

Parameter Type Required Description
id integer Required The email ID to delete

Example Request

DELETE /api.php/email/1

Success Response

{
  "success": true,
  "deleted_id": "1"
}

📊 Get Statistics

GET /stats

Retrieve system statistics.

Example Request

GET /api.php/stats

Success Response

{
  "success": true,
  "stats": {
    "id": 1,
    "total_emails": 1250,
    "total_addresses": 450,
    "total_received": 3200,
    "last_updated": "2026-01-24 14:30:00"
  }
}

🌍 Get Domains

GET /domains

Retrieve list of available email domains.

Example Request

GET /api.php/domains

Success Response

{
  "success": true,
  "domains": [
    "yourdomain.com",
    "tempmail.com",
    "disposable.email"
  ]
}

⚠️ Error Handling

The API uses standard HTTP response codes and returns JSON error messages.

Common Error Responses

Config Not Found

{
  "error": "Config not found"
}

Invalid Endpoint

{
  "error": "Invalid endpoint: /unknown"
}

Method Not Allowed

{
  "error": "Method not allowed"
}

💻 Usage Examples

JavaScript (Fetch API)

// Generate random email
const response = await fetch('/api.php/generate');
const data = await response.json();
console.log(data.email); // "budipratama123@yourdomain.com"

// Generate custom email
const customResponse = await fetch('/api.php/generate?username=myname');
const customData = await customResponse.json();
console.log(customData.email); // "myname@yourdomain.com"

// Get inbox
const inboxResponse = await fetch(`/api.php/inbox/${encodeURIComponent(email)}`);
const inbox = await inboxResponse.json();
console.log(inbox.emails);

// Get email detail
const emailResponse = await fetch('/api.php/email/1');
const emailData = await emailResponse.json();
console.log(emailData.email.body_html);

cURL

# Generate email
curl -X GET "https://yourdomain.com/api.php/generate"

# Generate custom email
curl -X GET "https://yourdomain.com/api.php/generate?username=johnsmith"

# Get inbox
curl -X GET "https://yourdomain.com/api.php/inbox/test@yourdomain.com"

# Get email detail
curl -X GET "https://yourdomain.com/api.php/email/1"

# Delete email
curl -X DELETE "https://yourdomain.com/api.php/email/1"

PHP

<?php
// Generate email
$response = file_get_contents('https://yourdomain.com/api.php/generate');
$data = json_decode($response, true);
echo $data['email'];

// Generate custom email
$username = 'johnsmith';
$response = file_get_contents("https://yourdomain.com/api.php/generate?username={$username}");
$data = json_decode($response, true);

// Get inbox
$email = urlencode('test@yourdomain.com');
$response = file_get_contents("https://yourdomain.com/api.php/inbox/{$email}");
$inbox = json_decode($response, true);
?>

📧 TempMail API v1.0

Built with ❤️ for temporary email service