# TempMail Platform API Documentation

This document describes the primary API endpoints used by the TempMail frontend to interact with the backend service. All endpoints return JSON responses.

---

## 1. Generate Email Address

Generates a new, random temporary email address.

**Endpoint:** `GET /api/generate.php`

**Query Parameters:**
- `domain` (optional): The domain to use for the email. If not provided, a random system domain is used.

**Example Request:**
```http
GET /api/generate.php?domain=cricketupdates.xyz
```

**Success Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "email": "abc123xyz@cricketupdates.xyz",
    "domain": "cricketupdates.xyz",
    "expires_in": "24 hours"
  }
}
```

**Error Response (429 Too Many Requests):**
```json
{
  "success": false,
  "message": "Rate limit exceeded"
}
```

---

## 2. Get Inbox

Retrieves the list of emails for a specific temporary email address.

**Endpoint:** `GET /api/inbox.php`

**Query Parameters:**
- `email` (required): The temporary email address to fetch the inbox for.
- `page` (optional): The page number for pagination. Default is `1`.
- `limit` (optional): The number of emails per page. Default is `20` (max `50`).

**Example Request:**
```http
GET /api/inbox.php?email=abc123xyz@cricketupdates.xyz&page=1&limit=20
```

**Success Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "emails": [
      {
        "id": 15,
        "from_email": "sender@example.com",
        "from_name": "John Doe",
        "subject": "Test Email",
        "received_at": "2026-03-09 10:00:00",
        "read": 0,
        "spam_score": 0.0,
        "is_spam": 0
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "total_pages": 1
    }
  }
}
```

**Error Response (400 Bad Request):**
```json
{
  "success": false,
  "message": "Valid email is required"
}
```

---

## 3. Read specific Email

Retrieves the full content and details of a specific email by its ID.

**Endpoint:** `GET /api/read.php`

**Query Parameters:**
- `id` (required): The unique ID of the email to read.

**Example Request:**
```http
GET /api/read.php?id=15
```

**Success Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "id": 15,
    "email_address": "abc123xyz@cricketupdates.xyz",
    "domain": "cricketupdates.xyz",
    "from_email": "sender@example.com",
    "from_name": "John Doe",
    "subject": "Test Email",
    "body": "Hello this is the plain text body",
    "body_html": "<p>Hello this is the HTML body</p>",
    "raw_email": "...",
    "attachments": null,
    "read": 1,
    "spam_score": 0.0,
    "is_spam": 0,
    "received_at": "2026-03-09 10:00:00",
    "expires_at": "2026-03-10 10:00:00",
    "created_at": "2026-03-09 10:00:00"
  }
}
```

**Error Response (404 Not Found):**
```json
{
  "success": false,
  "message": "Email not found or expired"
}
```

---

## 4. Delete Email

Deletes a specific email by its ID.

**Endpoint:** `POST /api/delete.php`

**Headers:**
- `Content-Type: application/json`

**Body:**
```json
{
  "id": 15
}
```

**Example Request:**
```http
POST /api/delete.php
Content-Type: application/json

{
  "id": 15
}
```

**Success Response (200 OK):**
```json
{
  "success": true,
  "message": "Email deleted successfully"
}
```

**Error Response (404 Not Found):**
```json
{
  "success": false,
  "message": "Email not found"
}
```