Về trang chủ
API Reference

REST API để tích hợp TempMail vào ứng dụng của bạn. Không cần xác thực — hoàn toàn miễn phí.

Base URL
Domains
GET /api/domains Lấy danh sách domain khả dụng ▼
Response
JSON{
  "domains": ["hungsmoke.site", "example.com"]
}
Ví dụ
cURLcurl
POST /api/domains/add Thêm domain mới (quét MX tự động) ▼
Request Body
FieldTypeRequiredDescription
domain string required Domain muốn thêm, ví dụ yourdomain.com
Response — Thành công
JSON{
  "ok": true,
  "domain": "yourdomain.com",
  "mx": [{ "priority": 10, "exchange": "mail.yourserver.com" }],
  "warning": null
}
Response — MX chưa cấu hình (HTTP 422)
JSON{
  "error": "mx_not_found",
  "message": "Không tìm thấy MX record cho yourdomain.com",
  "guide": {
    "type":     "MX",
    "host":     "@",
    "value":    "1.2.3.4",
    "priority": 10,
    "ttl":      300
  }
}
Mailbox
POST /api/new Tạo địa chỉ email ngẫu nhiên ▼
Response
JSON{
  "address":   "happyfox1234@hungsmoke.site",
  "expiresAt": 0,
  "ttl":       0
}
POST /api/custom Tạo địa chỉ email tuỳ chỉnh ▼
Request Body
FieldTypeRequiredDescription
username string required 1-40 ký tự, chỉ dùng a-z 0-9 . _ -
domain string required Phải là domain có trong hệ thống
Response
JSON{
  "address":   "myname@hungsmoke.site",
  "expiresAt": 0,
  "ttl":       0
}
GET /api/inbox/:address Lấy danh sách mail trong hộp thư ▼
Path Params
ParamTypeDescription
addressstringĐịa chỉ email đầy đủ, ví dụ foo@hungsmoke.site
Response
JSON{
  "messages": [
    {
      "id":          "uuid-v4",
      "receivedAt": "2026-03-29T10:00:00.000Z",
      "from":        "sender@example.com",
      "to":          "foo@hungsmoke.site",
      "subject":     "Hello World",
      "text":        "Nội dung thuần văn bản",
      "html":        "<p>Nội dung HTML</p>",
      "attachments": []
    }
  ],
  "expiresAt": 0
}
GET /api/mail/:address/:id Xem nội dung một email cụ thể ▼
Path Params
ParamTypeDescription
addressstringĐịa chỉ email
idstringUUID của mail (lấy từ inbox)
Response
JSON// Trả về object mail giống như trong mảng messages
{
  "id": "...",
  "subject": "...",
  // ... đầy đủ các field
}
DELETE /api/inbox/:address Xoá hộp thư và toàn bộ email ▼
Path Params
ParamTypeDescription
addressstringĐịa chỉ email cần xoá
Response
JSON{ "ok": true }
Statistics
GET /api/stats Thống kê tổng số mail đã nhận ▼
Response
JSON{ "totalMails": 1024 }
WebSocket Realtime
WS wss://<host> Nhận mail realtime qua WebSocket ▼

Kết nối WebSocket để nhận mail realtime thay vì polling. Server sẽ push ngay khi có mail mới.

Subscribe (Client → Server)
JSON{ "type": "subscribe", "address": "foo@hungsmoke.site" }
Server → Client: Inbox hiện tại
JSON{
  "type":      "inbox",
  "messages": [ /* array mail objects */ ],
  "expiresAt": 0
}
Server → Client: Mail mới đến
JSON{
  "type":    "new_mail",
  "message": { /* mail object */ }
}
Ví dụ JavaScript
JSconst ws = new WebSocket('wss://hungsmoke.site');

ws.onopen = () => ws.send(JSON.stringify({
  type: 'subscribe',
  address: 'foo@hungsmoke.site'
}));

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.type === 'new_mail') {
    console.log('📨 New mail:', msg.message.subject);
  }
};