🌟 Giới thiệu

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:

  • 📧 Đọc email với phân trang
  • 🗑️ Xóa email cụ thể
  • 🌐 Thêm domain mới
  • ✅ Kiểm tra trạng thái domain
📡 Base URL: https://tinyhost.shop
🔐 Xác thực: 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

📬 1. Đọc danh sách email

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

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

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

🔧 Ví dụ Request:

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

📤 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. Đọc chi tiết một email

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

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

📥 Parameters
domain (path) Tên miền email
user (path) Tên người dùng
email_id (path) ID của email

🔧 Ví dụ Request:

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

📤 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. Xóa một email

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

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

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

🔧 Ví dụ Request:

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

📤 Response:

{
  "status": "deleted"
}

🌐 4. Thêm domain mới

POST /api/add-domain/{domain}

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) Tên miền cần thêm (ví dụ: newdomain.com)

🔧 Ví dụ Request:

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

📤 Response khi thêm mới:

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

📤 Response khi cập nhật:

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

🎲 5. Lấy danh sách domain

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

GET /api/api/all-domains/

🔧 Ví dụ Request:

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

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

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

🔧 Ví dụ Request:

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

📤 Response:

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

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

GET /api/check-mx/{domain}

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

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

🔧 Ví dụ Request:

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

📤 Response (Online):

{
  "result": "online"
}

📤 Response (Offline):

{
  "result": "offline"
}

💻 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"

⚠️ Xử lý lỗi

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

📊 HTTP Status Codes

200 Thành công
400 Yêu cầu không hợp lệ (ví dụ: format email sai)
404 Không tìm thấy (domain, user hoặc email không tồn tại)
500 Lỗi server

📤 Ví dụ Response lỗi:

{
  "detail": "Domain not found"
}
💡 Mẹo xử lý lỗi:
  • Luôn kiểm tra status code trước khi xử lý response
  • Sử dụng try-catch để xử lý exception
  • Log lỗi để debug dễ dàng hơn

📝 Lưu ý quan trọng

✅ Validation email

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

🌐 Domain status

Chỉ các domain có MX record hợp lệ mới được coi là "online"

⚡ Rate limiting

Không có giới hạn rate hiện tại, nhưng nên sử dụng hợp lý

🗂️ Data retention

Email sẽ bị xóa sau 7 ngày

👤 User cleanup

User không hoạt động sẽ bị xóa sau 7 ngày