Tài liệu API

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

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);

Example Response

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

Thêm Tên miền riêng

Yêu cầu hệ thống xác thực và thêm tên miền của bạn vào danh sách hỗ trợ.

POST /api/add-custom-domain

Dữ liệu yêu cầu

Field	Type	Description
domain	string	Tên miền (vd: example.com)

cURL

JS

Python

curl -X POST "https://api.tempmailvip.io.vn/api/add-custom-domain" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "my-domain.com" }'

fetch("https://api.tempmailvip.io.vn/api/add-custom-domain", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ domain: "my-domain.com" })
}).then(res => res.json()).then(console.log);

import requests

url = "https://api.tempmailvip.io.vn/api/add-custom-domain"
data = {"domain": "my-domain.com"}
response = requests.post(url, json=data)
print(response.json())

Response (200 OK)

{ "success": true }

🔔 Thông báo hệ thống

Lấy danh sách các thông báo mới nhất từ Ban quản trị.

GET /api/notifications

Không yêu cầu tham số.

cURL

JS

Python

curl "https://api.tempmailvip.io.vn/api/notifications"

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

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

Response

[
  {
    "id": "uuid",
    "title": "Welcome",
    "message": "...",
    "type": "info",
    "date": "2026-01-14T..."
  }
]

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	Required	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

Dữ liệu yêu cầu

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": "..." }'

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

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

Response (200 OK)

{ "success": true, "user": { "username": "user123", "email": "..." } }

📧 Yêu cầu mã OTP

Gửi mã xác thực 6 số về email thật để khôi phục mật khẩu.

POST /api/auth/request-otp

Dữ liệu yêu cầu

Field	Type	Description
email	string	Email thật đã đăng ký.

cURL

JS

Python

curl -X POST "https://api.tempmailvip.io.vn/api/auth/request-otp" \
  -H "Content-Type: application/json" \
  -d '{ "email": "real@mail.com" }'

fetch("https://api.tempmailvip.io.vn/api/auth/request-otp", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "real@mail.com" })
}).then(res => res.json()).then(console.log);

import requests
response = requests.post("https://api.tempmailvip.io.vn/api/auth/request-otp", 
                         json={"email": "real@mail.com"})
print(response.json())

🔑 Đổi mật khẩu (OTP)

Sử dụng mã OTP đã nhận để thiết lập mật khẩu mới.

POST /api/user/change-password

Dữ liệu yêu cầu

Field	Type	Description
email	string	Email đã đăng ký.
otp	string	Mã 6 số.
newPassword	string	Mật khẩu mới.

cURL

JS

Python

curl -X POST "https://api.tempmailvip.io.vn/api/user/change-password" \
  -H "Content-Type: application/json" \
  -d '{ "email": "...", "otp": "...", "newPassword": "..." }'

fetch("https://api.tempmailvip.io.vn/api/user/change-password", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "...", otp: "...", newPassword: "..." })
}).then(res => res.json()).then(console.log);

import requests
data = { "email": "...", "otp": "...", "newPassword": "..." }
response = requests.post("https://api.tempmailvip.io.vn/api/user/change-password", json=data)
print(response.json())

Response Codes

✅ 200: Thành công

❌ err_otp_invalid: Mã sai/hết hạn

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=...

Tham số truy vấn

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

💾 Lưu hòm thư

Lưu địa chỉ email tạm thời vào danh sách quản lý của tài khoản.

POST /api/user/save-inbox

Request Body

Field	Type	Description
username	string	Tên đăng nhập.
email	string	Email tạm thời cần lưu.
note	string	Ghi chú ngắn (optional).

cURL

JS

Python

curl -X POST "https://api.tempmailvip.io.vn/api/user/save-inbox" \
  -H "Content-Type: application/json" \
  -d '{ "username": "u", "email": "e", "note": "..." }'

fetch("https://api.tempmailvip.io.vn/api/user/save-inbox", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ username: "u", email: "e", note: "..." })
}).then(res => res.json()).then(console.log);

import requests
data = { "username": "u", "email": "e", "note": "..." }
response = requests.post("https://api.tempmailvip.io.vn/api/user/save-inbox", json=data)
print(response.json())

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

Lấy danh sách các địa chỉ email đã lưu.

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

JSON

cURL

JS

Python

{ "inboxes": [ { "email": "...", "note": "...", "createdAt": "..." } ] }

curl "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
response = requests.get("https://api.tempmailvip.io.vn/api/user/inboxes", 
                        params={"username": "user123"})
print(response.json())

📝 Chỉnh sửa ghi chú

Cập nhật nội dung ghi chú cho hòm thư đã lưu.

POST /api/user/update-inbox-note

Request Body

Field	Type	Description
username	string	Tên đăng nhập.
email	string	Địa chỉ email.
note	string	Ghi chú mới.

cURL

JS

Python

curl -X POST "https://api.tempmailvip.io.vn/api/user/update-inbox-note" \
  -H "Content-Type: application/json" \
  -d '{ "username": "u", "email": "e", "note": "new note" }'

fetch("https://api.tempmailvip.io.vn/api/user/update-inbox-note", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ username: "u", email: "e", note: "new note" })
}).then(res => res.json()).then(console.log);

import requests
data = { "username": "u", "email": "e", "note": "new note" }
response = requests.post("https://api.tempmailvip.io.vn/api/user/update-inbox-note", json=data)
print(response.json())

🗑️ Xoá hòm thư lưu trữ

Gỡ bỏ địa chỉ email khỏi danh sách quản lý của tài khoản.

POST /api/user/delete-inbox

Request Body

Field	Type	Description
username	string	Tên đăng nhập.
email	string	Địa chỉ email.

cURL

JS

Python

curl -X POST "https://api.tempmailvip.io.vn/api/user/delete-inbox" \
  -H "Content-Type: application/json" \
  -d '{ "username": "u", "email": "e" }'

fetch("https://api.tempmailvip.io.vn/api/user/delete-inbox", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ username: "u", email: "e" })
}).then(res => res.json()).then(console.log);

import requests
data = { "username": "u", "email": "e" }
response = requests.post("https://api.tempmailvip.io.vn/api/user/delete-inbox", json=data)
print(response.json())

⚠️ 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ộ.

🔍 Mã lỗi chi tiết (Error Strings)

Các lỗi logic nghiệp vụ sẽ trả về chuỗi định danh trong field error.

Error String	Mô tả chi tiết
err_otp_invalid	Mã OTP không đúng hoặc đã hết hạn (5 phút).
err_email_used	Địa chỉ email thật đã được đăng ký bởi người khác.
err_domain_invalid	Tên miền riêng không đúng định dạng.
err_dns_not_configured	Tên miền chưa trỏ MX về Cloudflare.
Invalid credentials	Sai tên đăng nhập hoặc mật khẩu.
User/Email exists	Tài khoản đã tồn tại trong hệ thống.

JSON

{
  "success": false,
  "error": "err_otp_invalid"
}

💡 Thực tiễn tốt nhất

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

⚡ Giới hạn tốc độ

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

✅ Xác thực Email

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

🗂️ Lưu trữ dữ liệu

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

👤 Dọn dẹp người dùng

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

🔒 Bảo mật

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

JS

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');
}

Giới thiệu

Base URL

Xác thực

Lấy danh sách Domains

Phản hồi

Thêm Tên miền riêng

Dữ liệu yêu cầu

🔔 Thông báo hệ thống

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

Dữ liệu yêu cầu

📧 Yêu cầu mã OTP

Dữ liệu yêu cầu

🔑 Đổi mật khẩu (OTP)

Dữ liệu yêu cầu

Thông tin hồ sơ

Tham số truy vấn

💾 Lưu hòm thư

Request Body

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

📝 Chỉnh sửa ghi chú

Request Body

🗑️ Xoá hòm thư lưu trữ

Request Body

⚠️ Xử lý lỗi

📊 HTTP Status Codes

🔍 Mã lỗi chi tiết (Error Strings)

💡 Thực tiễn tốt nhất

📝 Lưu ý quan trọng

⚡ Giới hạn tốc độ

✅ Xác thực Email

🗂️ Lưu trữ dữ liệu

👤 Dọn dẹp người dùng

🔒 Bảo mật

Đă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

Notification Title

Xác nhận