📋 Table of contents 📋 Mục lục
🌟 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
🔗 API Endpoints 🔗 API Endpoints
📬 1. List emails 📬 1. Đọc danh sách email
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
🔧 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
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
🔧 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
Description: Delete a specific email.
Mô tả: Xóa một email cụ thể.
📥 Parameters
🔧 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
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
🔧 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:
🔧 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 :
📥 Parameters
🔧 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
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
🔧 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
📤 Example error response:📤 Ví dụ Response lỗi:
{
"detail": "Domain not found"
}
- 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.