Tài liệu REST API

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

Lấy danh sách email của một user, có phân trang. Phản hồi danh sách chỉ gồm metadata (không có body / html_body).

Tham số	Vị trí	Mô tả
domain	path	Tên miền email, vd example.com
user	path	Tên người dùng, vd testuser
page	query, tùy chọn	Số trang (mặc định 1)
limit	query, tùy chọn	Số item/trang (mặc định 20, tối đa 100)

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

{
  "emails": [
    {
      "id": 123,
      "subject": "Welcome",
      "sender": "[email protected]",
      "date": "2026-09-30T10:30:00.000Z",
      "has_attachments": false,
      "size": 1234
    }
  ],
  "total": 5,
  "page": 1,
  "limit": 20,
  "has_more": false
}

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

Lấy nội dung chi tiết một email.

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

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

Xóa một email cụ thể.

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

{ "status": "deleted" }

POST/api/add-domain/{domain}

Thêm domain mới hoặc cập nhật trạng thái online của domain đã có. Domain phải có MX record trỏ đúng về hostname của hệ thống mới được chấp nhận (status added, is_online: true).

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

// Khi thêm thành công
{ "status": "added", "domain": "newdomain.com", "is_online": true }

// Khi domain đã tồn tại, cập nhật lại trạng thái
{ "status": "updated", "domain": "newdomain.com", "is_online": false }

GET/api/all-domains/ & /api/random-domains/

Toàn bộ domain online (riêng tư, cần token):

curl -X GET "https://BASE_URL/api/all-domains/" \
  -H "X-Domain-Token: YOUR_TOKEN"

Domain online ngẫu nhiên (công khai):

curl -X GET "https://BASE_URL/api/random-domains/?limit=10"

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

GET/api/check-mx/{domain}

Kiểm tra domain đã có MX record hợp lệ trỏ về hệ thống chưa.

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

{ "result": "online" }   // hoặc "offline"

Xử lý lỗi

Mã	Ý nghĩa
200	Thành công
400	Request không hợp lệ (vd sai định dạng domain/email)
401	Thiếu/sai token cho endpoint riêng tư
404	Không tìm thấy email
429	Vượt rate-limit

{ "detail": "Domain not found" }

Lưu ý quan trọng

• Email phải đúng định dạng [email protected]
• Chỉ domain có MX record hợp lệ mới ở trạng thái "online"
• Email và domain không hoạt động sẽ tự động bị xóa sau 3 ngày
• Dịch vụ chỉ nhận mail — không hỗ trợ gửi/SMTP relay
• API có rate-limit theo IP
• Thời hạn lưu 3 ngày áp dụng cho dịch vụ đang hoạt động; bản sao lưu có thể giữ dữ liệu lâu hơn. Không bảo đảm xóa vĩnh viễn khỏi mọi bản sao vào thời điểm đó.
• Hộp thư dùng domain riêng vẫn công khai và có thể bị dịch vụ bên thứ ba chặn. Không bảo đảm địa chỉ được chấp nhận hay thư được chuyển đến.