TempMail API Documentation

Giới thiệu

Chào mừng bạn đến với tài liệu API của TempMail. API của chúng tôi cho phép bạn tạo, quản lý và nhận email tạm thời theo chương trình.

Tất cả các phản hồi đều ở định dạng JSON. Chúng tôi sử dụng các mã trạng thái HTTP tiêu chuẩn để chỉ thị sự thành công hoặc thất bại của các yêu cầu.

Base URL

https://api.tempmailvip.io.vn

Thay thế `api.tempmailvip.io.vn` bằng backend URL thực tế của bạn nếu đang chạy ở môi trường khác.

Xác thực

Hầu hết các API công cộng không yêu cầu xác thực. Tuy nhiên, các API Admin yêu cầu một khóa bí mật trong Header.

Header	Mô tả
X-Admin-Secret	Mã bí mật Admin cho các yêu cầu quản trị.

Lấy danh sách Domains

Trả về danh sách các tên miền email hiện có hỗ trợ.

GET /api/domains

Phản hồi

Field	Type	Description
success	boolean	Trạng thái yêu cầu.
domains	array	Danh sách các domain.

cURL

JS

Python

curl -X GET "https://api.tempmailvip.io.vn/api/domains"

fetch("https://api.tempmailvip.io.vn/api/domains")
  .then(res => res.json())
  .then(console.log);

import requests

url = "https://api.tempmailvip.io.vn/api/domains"
response = requests.get(url)
print(response.json())

Example Response (200 OK)

{
  "success": true,
  "domains": [
    "tempmailvip.io.vn"
  ]
}

Danh sách tin nhắn

Lấy danh sách tất cả email nhận được cho một địa chỉ email cụ thể.

GET /api/messages

Query Parameters

Parameter	Type	Required	Description
email	string	Có	Địa chỉ email cần kiểm tra.
page	integer	Không	Số trang (mặc định 1).

cURL

JS

Python

curl -X GET "https://api.tempmailvip.io.vn/api/messages?email=test@tempmailvip.io.vn"

fetch("https://api.tempmailvip.io.vn/api/messages?email=test@tempmailvip.io.vn")
  .then(res => res.json())
  .then(console.log);

import requests

url = "https://api.tempmailvip.io.vn/api/messages"
params = {"email": "test@tempmailvip.io.vn"}
response = requests.get(url, params=params)
print(response.json())

Example Response

{
  "messages": [
    {
      "id": "uuid-v4",
      "from": "sender@example.com",
      "subject": "Hello World",
      "body": "HTML content here...",
      "time": "2026-01-11T...",
      "isRead": false
    }
  ],
  "pagination": {
    "page": 1,
    "total": 1,
    "totalPages": 1
  }
}

Real-time Updates (SSE)

Sử dụng Server-Sent Events để nhận thông báo ngay lập tức khi có email mới đến.

SSE /api/sse

Thiết lập kết nối Server-Sent Events để nhận thông báo thời gian thực.

Query Parameters

Parameter	Type	Description
email	string	Email cần theo dõi.

cURL

JS

Python

curl -N "https://api.tempmailvip.io.vn/api/sse?email=user@tempmailvip.io.vn"

const eventSource = new EventSource(
  "https://api.tempmailvip.io.vn/api/sse?email=user@tempmailvip.io.vn"
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'update') {
    console.log("New message arriving!");
  }
};

import requests

url = "https://api.tempmailvip.io.vn/api/sse?email=user@tempmailvip.io.vn"
response = requests.get(url, stream=True)

for line in response.iter_lines():
    if line:
        print(f"Update: {line.decode('utf-8')}")

Stream Event Example

{
  "type": "update",
  "newCount": 1
}

Đánh dấu đã đọc

Đánh dấu một tin nhắn cụ thể là đã đọc.

POST /api/messages/mark-read

Request Body

Field	Type	Description
email	string	Địa chỉ email.
id	string	ID tin nhắn.

cURL

JS

Python

curl -X POST "https://api.tempmailvip.io.vn/api/messages/mark-read" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@tempmailvip.io.vn",
    "id": "msg-123"
  }'

fetch("https://api.tempmailvip.io.vn/api/messages/mark-read", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "test@tempmailvip.io.vn",
    id: "msg-123"
  })
}).then(res => res.json()).then(console.log);

import requests

url = "https://api.tempmailvip.io.vn/api/messages/mark-read"
data = {
    "email": "test@tempmailvip.io.vn",
    "id": "msg-123"
}
response = requests.post(url, json=data)
print(response.json())

Response (200 OK)

{ "success": true }

Xoá tin nhắn

Xoá một hoặc toàn bộ tin nhắn trong hòm thư.

DELETE /api/messages

Query Parameters

Parameter	Type	Description
email	string	Địa chỉ email.
id	string	ID (bỏ trống để xoá hết).

cURL

JS

Python

curl -X DELETE "https://api.tempmailvip.io.vn/api/messages?email=t@tempmailvip.io.vn&id=msg1"

fetch("https://api.tempmailvip.io.vn/api/messages?email=t@tempmailvip.io.vn&id=msg1", {
  method: "DELETE"
}).then(res => res.json()).then(console.log);

import requests

url = "https://api.tempmailvip.io.vn/api/messages"
params = {"email": "t@tempmailvip.io.vn", "id": "msg1"}
response = requests.delete(url, params=params)
print(response.json())

Response (200 OK)

{ "success": true }

Đăng ký người dùng

Tạo tài khoản mới để quản lý các hòm thư tạm thời.

POST /api/auth/register

Request Body

Field	Type	Required	Description
username	string	Có	Ít nhất 3 ký tự.
email	string	Có	Email thật để nhận OTP.
password	string	Có	Ít nhất 6 ký tự.

cURL

JS

Python

curl -X POST "https://api.tempmailvip.io.vn/api/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "email": "user@example.com",
    "password": "strongpassword"
  }'

fetch("https://api.tempmailvip.io.vn/api/auth/register", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    username: "newuser",
    email: "user@example.com",
    password: "strongpassword"
  })
}).then(res => res.json()).then(console.log);

import requests

url = "https://api.tempmailvip.io.vn/api/auth/register"
data = {
    "username": "newuser",
    "email": "user@example.com",
    "password": "strongpassword"
}
response = requests.post(url, json=data)
print(response.json())

Response

{ "success": true }

Đăng nhập

Xác thực người dùng và nhận thông tin tài khoản.

POST /api/auth/login

Request Body

Field	Type	Description
username	string	Tên đăng nhập.
password	string	Mật khẩu.

cURL

JS

Python

curl -X POST "https://api.tempmailvip.io.vn/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "user123",
    "password": "password123"
  }'

fetch("https://api.tempmailvip.io.vn/api/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    username: "user123",
    password: "password123"
  })
}).then(res => res.json()).then(console.log);

import requests

url = "https://api.tempmailvip.io.vn/api/auth/login"
data = {
    "username": "user123",
    "password": "password123"
}
response = requests.post(url, json=data)
print(response.json())

Example Response

{
  "success": true,
  "user": {
    "username": "user123",
    "email": "real@example.com"
  }
}

Thông tin hồ sơ

Lấy thông tin chi tiết của người dùng đang đăng nhập.

GET /api/user/get-profile?username=...

Query Parameters

Parameter	Type	Description
username	string	Tên đăng nhập.

cURL

JS

Python

curl -X GET "https://api.tempmailvip.io.vn/api/user/get-profile?username=user123"

fetch("https://api.tempmailvip.io.vn/api/user/get-profile?username=user123")
  .then(res => res.json())
  .then(console.log);

import requests

url = "https://api.tempmailvip.io.vn/api/user/get-profile"
params = {"username": "user123"}
response = requests.get(url, params=params)
print(response.json())

Response

{
  "username": "user123",
  "email": "test@example.com"
}

Danh sách hòm thư đã lưu

Lấy danh sách các địa chỉ email tạm thời mà người dùng đã lưu vào tài khoản.

GET /api/user/inboxes?username=...

Query Parameters

Parameter	Type	Description
username	string	Tên đăng nhập.

cURL

JS

Python

curl -X GET "https://api.tempmailvip.io.vn/api/user/inboxes?username=user123"

fetch("https://api.tempmailvip.io.vn/api/user/inboxes?username=user123")
  .then(res => res.json())
  .then(console.log);

import requests

url = "https://api.tempmailvip.io.vn/api/user/inboxes"
params = {"username": "user123"}
response = requests.get(url, params=params)
print(response.json())

Response

{
  "success": true,
  "inboxes": [
    { "address": "temp@tempmailvip.io.vn" }
  ]
}

⚠️ Xử lý lỗi

API trả về các mã lỗi HTTP tiêu chuẩn. Luôn kiểm tra status code trước khi xử lý response.

📊 HTTP Status Codes

Code	Ý nghĩa	Mô tả
200	OK	Yêu cầu thành công.
400	Bad Request	Dữ liệu đầu vào không hợp lệ.
401	Unauthorized	Thiếu hoặc sai thông tin xác thực.
404	Not Found	Không tìm thấy tài nguyên.
429	Too Many Requests	Vượt quá giới hạn rate limit.
500	Server Error	Lỗi server nội bộ.

Ví dụ Response lỗi

{
  "success": false,
  "error": "Invalid email format"
}

💡 Best Practices

Luôn sử dụng try-catch để xử lý exception
Log lỗi để debug dễ dàng hơn
Hiển thị thông báo lỗi thân thiện cho người dùng
Retry với exponential backoff cho lỗi 429, 500

📝 Lưu ý quan trọng

⚡ Rate Limiting

API giới hạn 60 requests/phút cho mỗi IP address. Vượt quá sẽ nhận HTTP 429.

✅ Email Validation

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

🗂️ Data Retention

Email sẽ được lưu trữ trong 7 ngày, sau đó tự động xóa.

👤 User Cleanup

Tài khoản không hoạt động sẽ bị xóa sau 30 ngày.

🔒 Security

Không chia sẻ thông tin đăng nhập
Sử dụng HTTPS cho mọi request
Không lưu password dưới dạng plain text
Thường xuyên đổi mật khẩu

Ví dụ xử lý Rate Limit

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || 60;
      console.log(`Rate limited. Retry after ${retryAfter}s`);
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue;
    }
    
    return response;
  }
  throw new Error('Max retries exceeded');
}

Tài liệu API

Giới thiệu

Base URL

Xác thực

Lấy danh sách Domains

Phản hồi

Danh sách tin nhắn

Query Parameters

Real-time Updates (SSE)

Query Parameters

Đánh dấu đã đọc

Request Body

Xoá tin nhắn

Query Parameters

Đăng ký người dùng

Request Body

Đăng nhập

Request Body

Thông tin hồ sơ

Query Parameters

Danh sách hòm thư đã lưu

Query Parameters

⚠️ Xử lý lỗi

📊 HTTP Status Codes

💡 Best Practices

📝 Lưu ý quan trọng

⚡ Rate Limiting

✅ Email Validation

🗂️ Data Retention

👤 User Cleanup

🔒 Security

Đăng nhập

Đăng ký

admin

Hòm thư của tôi

Khôi phục mật khẩu

Đổi mật khẩu

Phím tắt nhanh

Notification Title

Xác nhận

Mã QR Email