🌟 Introduction 🌟 Giới thiệu

The Temp Mail API allows you to manage temporary inboxes via HTTP. Supported operations:

API Temp Mail cho phép bạn quản lý email tạm thời thông qua các cuộc gọi HTTP. Bạn có thể thực hiện các thao tác sau:

  • 📧 Read emails with pagination📧 Đọc email với phân trang
  • 🗑️ Delete specific emails🗑️ Xóa email cụ thể
  • 🌐 Add new domains🌐 Thêm domain mới
  • ✅ Check domain status✅ Kiểm tra trạng thái domain
📡 Base URL: https://tinyhost.shop
🔐 Authentication: 🔐 Xác thực: The API currently does not require authentication. Please ensure domain and user inputs are valid. API hiện tại không yêu cầu xác thực, nhưng cần đảm bảo domain và user email hợp lệ.

🔗 API Endpoints 🔗 API Endpoints

📬 1. List emails 📬 1. Đọc danh sách email

GET /api/email/{domain}/{user}/

Description: Fetch a user's inbox with pagination.

Mô tả: Lấy danh sách email của một user cụ thể với phân trang.

📥 Parameters
domain (path) Email domain (e.g. example.com)Tên miền email (ví dụ: example.com)
user (path) Username (e.g. testuser)Tên người dùng (ví dụ: testuser)
page (query, optional) Page number (default: 1)Số trang (mặc định: 1)
limit (query, optional) Items per page (default: 20, max: 100)Số email trên mỗi trang (mặc định: 20, tối đa: 100)

🔧 Example request:🔧 Ví dụ Request:

curl -X GET "https://tinyhost.shop/api/email/example.com/testuser/?page=1&limit=20"

📤 Response:📤 Response:

{
  "emails": [
    {
      "id": 123,
      "subject": "Welcome to our service",
      "sender": "noreply@company.com",
      "date": "2025-07-08T10:30:00",
      "body": "Email content here...",
      "html_body": "<p>Email content here...</p>",
      "has_attachments": false
    }
  ],
  "total": 5,
  "page": 1,
  "limit": 20,
  "has_more": false
}

📖 2. Read email detail 📖 2. Đọc chi tiết một email

GET /api/email/{domain}/{user}/{email_id}

Description: Fetch the full content of a specific email.

Mô tả: Lấy nội dung chi tiết của một email cụ thể.

📥 Parameters
domain (path) Email domainTên miền email
user (path) UsernameTên người dùng
email_id (path) Email IDID của email

🔧 Example request:🔧 Ví dụ Request:

curl -X GET "https://tinyhost.shop/api/email/example.com/testuser/123"

📤 Response:📤 Response:

{
  "id": 123,
  "subject": "Welcome to our service",
  "sender": "noreply@company.com",
  "date": "2025-07-08T10:30:00",
  "body": "Email content here...",
  "html_body": "<p>Email content here...</p>",
  "has_attachments": false
}

🗑️ 3. Delete an email 🗑️ 3. Xóa một email

DELETE /api/email/{domain}/{user}/{email_id}

Description: Delete a specific email.

Mô tả: Xóa một email cụ thể.

📥 Parameters
domain (path) Email domainTên miền email
user (path) UsernameTên người dùng
email_id (path) Email ID to deleteID của email cần xóa

🔧 Example request:🔧 Ví dụ Request:

curl -X DELETE "https://tinyhost.shop/api/email/example.com/testuser/123"

📤 Response:📤 Response:

{
  "status": "deleted"
}

🌐 4. Add a domain 🌐 4. Thêm domain mới

POST /api/add-domain/{domain}

Description: Add a domain to the system or update existing status.

Mô tả: Thêm một domain mới vào hệ thống hoặc cập nhật trạng thái domain hiện có.

📥 Parameters
domain (path) Domain to add (e.g. newdomain.com)Tên miền cần thêm (ví dụ: newdomain.com)

🔧 Example request:🔧 Ví dụ Request:

curl -X POST "https://tinyhost.shop/api/add-domain/newdomain.com"

📤 Response (added):📤 Response khi thêm mới:

{
  "status": "added",
  "domain": "newdomain.com",
  "is_online": true
}

📤 Response (updated):📤 Response khi cập nhật:

{
  "status": "updated", 
  "domain": "newdomain.com",
  "is_online": false
}

🎲 5. Get domains 🎲 5. Lấy danh sách domain

Get all online domains:Lấy toàn bộ danh sách các domain online:

GET /api/api/all-domains/

🔧 Example request:🔧 Ví dụ Request:

curl -X GET "https://tinyhost.shop/api/all-domains/"

Get random online domains:Lấy ngẫu nhiên domain online :

GET /api/random-domains/
📥 Parameters
page (query, optional) Page number (default: 1)Số trang (mặc định: 1)
limit (query, optional) Items per page (default: 20, max: 50)Số domain trên mỗi trang (mặc định: 20, tối đa: 50)

🔧 Example request:🔧 Ví dụ Request:

curl -X GET "https://tinyhost.shop/api/random-domains/?limit=10"

📤 Response:📤 Response:

{
  "domains": [
    "domain1.com",
    "domain2.com", 
    "domain3.com"
  ],
  "total": 3
}

✅ 6. Check MX record status ✅ 6. Kiểm tra trạng thái MX record của domain

GET /api/check-mx/{domain}

Description: Check whether a domain has a valid MX record.

Mô tả: Kiểm tra xem domain có MX record hợp lệ không.

📥 Parameters
domain (path) Domain to checkTên miền cần kiểm tra

🔧 Example request:🔧 Ví dụ Request:

curl -X GET "https://tinyhost.shop/api/check-mx/example.com"

📤 Response (Online):📤 Response (Online):

{
  "result": "online"
}

📤 Response (Offline):📤 Response (Offline):

{
  "result": "offline"
}

💻 Examples 💻 Ví dụ sử dụng

🐍 Python Example

import requests
import json

# Base URL của API
BASE_URL = "https://tinyhost.shop"

class TempMailAPI:
    def __init__(self, base_url=BASE_URL):
        self.base_url = base_url
    
    def get_emails(self, domain, user, page=1, limit=20):
        """Lấy danh sách email"""
        url = f"{self.base_url}/api/email/{domain}/{user}/"
        params = {"page": page, "limit": limit}
        response = requests.get(url, params=params)
        return response.json()
    
    def get_email_detail(self, domain, user, email_id):
        """Lấy chi tiết một email"""
        url = f"{self.base_url}/api/email/{domain}/{user}/{email_id}"
        response = requests.get(url)
        return response.json()
    
    def delete_email(self, domain, user, email_id):
        """Xóa một email"""
        url = f"{self.base_url}/api/email/{domain}/{user}/{email_id}"
        response = requests.delete(url)
        return response.json()
    
    def add_domain(self, domain):
        """Thêm domain mới"""
        url = f"{self.base_url}/api/add-domain/{domain}"
        response = requests.post(url)
        return response.json()
    
    def get_random_domains(self, limit=20):
        """Lấy danh sách domain ngẫu nhiên"""
        url = f"{self.base_url}/api/random-domains/"
        params = {"limit": limit}
        response = requests.get(url, params=params)
        return response.json()

# Sử dụng
api = TempMailAPI()

# Lấy danh sách domain
domains = api.get_random_domains(10)
print("Available domains:", domains)

# Thêm domain mới
result = api.add_domain("mydomain.com")
print("Add domain result:", result)

# Lấy email
emails = api.get_emails("example.com", "testuser")
print("Emails:", emails)

# Xem chi tiết email đầu tiên (nếu có)
if emails['emails']:
    email_detail = api.get_email_detail("example.com", "testuser", emails['emails'][0]['id'])
    print("Email detail:", email_detail)
    
    # Xóa email
    delete_result = api.delete_email("example.com", "testuser", emails['emails'][0]['id'])
    print("Delete result:", delete_result)
	
}

🟨 JavaScript/Node.js Example

const axios = require('axios');

class TempMailAPI {
    constructor(baseUrl = 'https://tinyhost.shop') {
        this.baseUrl = baseUrl;
    }
    
    async getEmails(domain, user, page = 1, limit = 20) {
        const response = await axios.get(`${this.baseUrl}/api/email/${domain}/${user}/`, {
            params: { page, limit }
        });
        return response.data;
    }
    
    async getEmailDetail(domain, user, emailId) {
        const response = await axios.get(`${this.baseUrl}/api/email/${domain}/${user}/${emailId}`);
        return response.data;
    }
    
    async deleteEmail(domain, user, emailId) {
        const response = await axios.delete(`${this.baseUrl}/api/email/${domain}/${user}/${emailId}`);
        return response.data;
    }
    
    async addDomain(domain) {
        const response = await axios.post(`${this.baseUrl}/api/add-domain/${domain}`);
        return response.data;
    }
    
    async getRandomDomains(limit = 20) {
        const response = await axios.get(`${this.baseUrl}/api/random-domains/`, {
            params: { limit }
        });
        return response.data;
    }
}

// Sử dụng
(async () => {
    const api = new TempMailAPI();
    
    try {
        // Lấy domains
        const domains = await api.getRandomDomains(5);
        console.log('Domains:', domains);
        
        // Thêm domain
        const addResult = await api.addDomain('testdomain.com');
        console.log('Add domain:', addResult);
        
        // Lấy emails
        const emails = await api.getEmails('example.com', 'testuser');
        console.log('Emails:', emails);
        
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
    }
})();

🌐 cURL Examples

# Lấy danh sách email
curl -X GET "https://tinyhost.shop/api/email/example.com/testuser/?page=1&limit=5"

# Xem chi tiết email
curl -X GET "https://tinyhost.shop/api/email/example.com/testuser/123"

# Xóa email
curl -X DELETE "https://tinyhost.shop/api/email/example.com/testuser/123"

# Thêm domain mới
curl -X POST "https://tinyhost.shop/api/add-domain/mydomain.com"

# Lấy domain ngẫu nhiên
curl -X GET "https://tinyhost.shop/api/random-domains/?limit=10"

# Kiểm tra MX record
curl -X GET "https://tinyhost.shop/api/check-mx/example.com"

⚠️ Error Handling ⚠️ Xử lý lỗi

The API returns standard HTTP status codes:

API trả về các mã lỗi HTTP tiêu chuẩn:

📊 HTTP Status Codes

200 SuccessThành công
400 Bad request (e.g., invalid email format)Yêu cầu không hợp lệ (ví dụ: format email sai)
404 Not found (domain, user, or email does not exist)Không tìm thấy (domain, user hoặc email không tồn tại)
500 Server errorLỗi server

📤 Example error response:📤 Ví dụ Response lỗi:

{
  "detail": "Domain not found"
}
💡 Error handling tips:💡 Mẹo xử lý lỗi:
  • Always check the status code before processing the responseLuôn kiểm tra status code trước khi xử lý response
  • Use try-catch to handle exceptionsSử dụng try-catch để xử lý exception
  • Log errors for easier debuggingLog lỗi để debug dễ dàng hơn

📝 Important Notes 📝 Lưu ý quan trọng

✅ Validation email

Email must be a valid format (user@domain.com) Email phải có format hợp lệ (user@domain.com)

🌐 Domain status

Only domains with a valid MX record are considered "online" Chỉ các domain có MX record hợp lệ mới được coi là "online"

🗂️ Data retention

Emails will be deleted after 3 days Email sẽ bị xóa sau 3 ngày

👤 User cleanup

Inactive users will be deleted after 3 days User không hoạt động sẽ bị xóa sau 3 ngày

🚨 Abuse Prevention & Limitations

  • API is rate-limited per IP and per endpoint.
  • No outbound email or SMTP relay is provided.
  • Automated abuse or misuse may result in IP or domain blocking.
  • We actively monitor abnormal usage patterns.