📋 Mục lục
🌟 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