Asynchronous Temp Mail Server (SMTP + Web API)

A fast, highly performant, and self-contained temporary email system. It runs both an SMTP receiver on port 25 and a Web API/Dashboard on port 5005 inside a single asynchronous Python process using FastAPI, aiosmtpd, and uvicorn.

✨ Features

• Single Process Asynchronous Architecture: Leverages python asyncio to run both SMTP and REST HTTP/Web servers with minimal CPU and memory overhead.
• Beautiful Web Interface: Serves a premium dark-themed inbox dashboard at the root URL (http://<your-ip>:5005) for generating emails, auto-polling incoming messages, and reading rich HTML emails securely inside sandboxed iframes.
• SQLite Storage & Auto-Cleanup: Automatically retains email metadata and contents in a lightweight SQLite database, and schedules automatic cleanup of emails and addresses older than 24 hours.
• Reboot Survival: Comes with a pre-configured systemd service template to run continuously in the background on Linux servers.

---

🚀 Quick Start

1. Prerequisites

Make sure python3, pip, and Git are installed on your server. Port 25 (SMTP) and Port 5005 (Web API) must be open and not occupied by other services.

2. Install Dependencies

pip3 install -r requirements.txt

3. Run the Server Manually

sudo python3 server.py

Note: Root/sudo privileges are required to bind to port 25.

---

⚙️ Systemd Service Integration (Auto-run on Boot)

To ensure the server survives reboots and automatically restarts if it crashes, you can install it as a native Linux service:

1. Copy the systemd service file:

   sudo cp tempmail.service /etc/systemd/system/tempmail.service

2. Reload systemd daemon configurations:

   sudo systemctl daemon-reload

3. Enable and start the service:

   sudo systemctl enable tempmail.service
   sudo systemctl start tempmail.service

4. Verify the service is running:

   sudo systemctl status tempmail.service

---

📡 API Documentation

1. Create a Temporary Address

Generates a random 8-character email address with the default domain.

• Request:

  curl -X POST 'http://<your-ip>:5005/create' -H 'Content-Length: 0'

• Response:

  {
    "email": "3kxgflgg@mostafa.lu"
  }

2. List Inbox Messages

Lists all received emails for a specific address.

• Request:

  curl -X GET 'http://<your-ip>:5005/messages?address=3kxgflgg@mostafa.lu'

• Response:

  {
    "messages": [
      {
        "id": "11591be7-b84f-43f4-a2ad-669c091bce5e",
        "address": "3kxgflgg@mostafa.lu",
        "from_addr": "mostafaashry115@gmail.com",
        "subject": "sub",
        "received_at": 1781612494184
      }
    ]
  }

3. Read Message Details

Retrieves text, HTML content, and full details of a specific message.

• Request:

  curl -X GET 'http://<your-ip>:5005/message/11591be7-b84f-43f4-a2ad-669c091bce5e'

• Response:

  {
    "id": "11591be7-b84f-43f4-a2ad-669c091bce5e",
    "address": "3kxgflgg@mostafa.lu",
    "from_addr": "mostafaashry115@gmail.com",
    "subject": "sub",
    "text": "msg\n",
    "html": "",
    "received_at": 1781612494184
  }