Lưu Vân Mail API

Tạo và quản lý email tạm thời qua REST API. Sử dụng cho automation, testing, bảo mật, hoặc bất kỳ workflow nào cần email dùng một lần.

BASE URL

https://vibecoder.io.vn

⚡ Miễn phí. Mặc định mỗi API key được 100 request/giờ. Admin có thể tăng giới hạn cho từng key.

Multi-domain

Hệ thống hỗ trợ nhiều domain email. Danh sách domain hiện có:

domains
vibecoder.io.vn
luuvan.site
luuvan.indevs.in
locpnv.indevs.in
lhuniverse.io.vn
locpnv.click
locpnv.site

⚠ Các domain đang chờ kích hoạt DNS (zone pending), không nhận được email: luuvan.indevs.in, locpnv.indevs.in, locpnv.site

Tính năng chính

Tính năng	Mô tả
Multi-domain	Chọn domain khi tạo email. Gọi `GET /api/domains` để xem danh sách + pending status.
User Dashboard	/dashboard — Quản lý mailbox, xem inbox, tạo API key.
Recovery Key	Mỗi mailbox có RK để khôi phục. Dùng cho guest không cần đăng nhập.
Admin Panel	/admin — Quản lý mailbox, messages, API keys, thành viên.
Auto Cleanup	Cron job mỗi 5 phút tự xóa mailbox hết hạn.

Xác thực (Authentication)

Mọi request đến API đều cần Bearer token trong header Authorization.

HTTP Header
Authorization: Bearer tm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Lấy API Key

Có 2 cách lấy API Key:

Cách	Mô tả
Tự tạo	Đăng ký tài khoản → đăng nhập → gọi `POST /api/register` hoặc vào Dashboard. Mỗi tài khoản được 1 key, 100 req/h.
Admin cấp	Admin tạo key qua panel `/admin` — rate limit mặc định: 1000 req/giờ, có thể tuỳ chỉnh.

Đăng ký API Key

Bạn cần đăng ký tài khoản trước. Mỗi tài khoản được 1 API key duy nhất. Key chỉ hiển thị 1 lần — hãy lưu lại ngay.

POST/api/register

🔒 Yêu cầu đăng nhập. Gọi API này với cookie session hoặc vào Dashboard để tạo key.

Tham số	Kiểu	Bắt buộc	Mô tả
name	string	Yêu cầu	Tên ứng dụng của bạn (2-80 ký tự)

curl
# Đăng ký API key mới
curl -X POST https://vibecoder.io.vn/api/register \
  -H "Content-Type: application/json" \
  -H "Cookie: tempmail_user_session=..." \
  -d '{"name": "My Cool App"}'

javascript
// Phải đăng nhập trước (cookie session tự gửi)
const res = await fetch('https://vibecoder.io.vn/api/register', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'My Cool App' })
});
const data = await res.json();
console.log(data.apiKey); // tm_xxxx... (lưu lại ngay!)

201 Thành công

json
{
  "apiKey": "tm_ABCxyz123...",
  "rateLimit": 100,
  "rateLimitPeriod": "hour",
  "message": "Save this API key. It will only be shown once."
}

⚠ Mỗi tài khoản chỉ tạo được 1 key. Nếu cần key mới hoặc tăng rate limit, liên hệ admin.

Tạo API Key

Đang kiểm tra đăng nhập...

Rate Limits

Mỗi API key có giới hạn số request trên mỗi khung giờ. Admin có thể thay đổi giới hạn cho từng key.

100

User key (mặc định)

1,000

Admin key (mặc định)

∞

Bootstrap key (env)

Response Headers

Mọi response từ Bearer API đều chứa rate limit headers:

HTTP Headers
X-RateLimit-Limit: 100        # Tổng request được phép/giờ
X-RateLimit-Remaining: 95    # Request còn lại
X-RateLimit-Reset: 2025-01-01T... # Thời điểm reset

429 Khi vượt giới hạn

json
{
  "error": "Rate limit exceeded.",
  "limit": 100,
  "resetAt": "2025-01-01T12:00:00.000Z"
}

Mã lỗi

HTTP Code	Mô tả
400	Dữ liệu gửi lên không hợp lệ (thiếu tham số, sai format)
401	Thiếu Authorization header hoặc Bearer token
403	API key không hợp lệ hoặc đã bị thu hồi
404	Mailbox hoặc message không tìm thấy
409	Mailbox đã tồn tại hoặc IP đã đăng ký key
429	Vượt giới hạn rate limit
500	Lỗi server nội bộ

Mọi lỗi đều trả về JSON với field error:

json
{ "error": "Mailbox not found or expired." }

Tạo Mailbox

POST/mailboxes

Tạo email tạm thời mới. Có thể chọn prefix hoặc để hệ thống random.

Tham số	Kiểu	Bắt buộc	Mô tả
prefix	string	Tuỳ chọn	Phần đầu email (1-32 ký tự, a-z 0-9 . _ -). Để trống = random.
ttlMinutes	number	Tuỳ chọn	Thời hạn sống (phút). Mặc định: 60. Tối đa: 1440.

curl
curl -X POST https://vibecoder.io.vn/mailboxes \
  -H "Authorization: Bearer tm_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prefix": "otp-test", "ttlMinutes": 30}'

javascript
const res = await fetch('https://vibecoder.io.vn/mailboxes', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer $\{API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ prefix: 'otp-test', ttlMinutes: 30 })
});
const data = await res.json();

201 Thành công

json
{
  "mailbox": {
    "address": "otp-test@vibecoder.io.vn",
    "label": "otp-test",
    "createdAt": "2025-01-01T12:00:00.000Z",
    "expiresAt": "2025-01-01T12:30:00.000Z"
  },
  "recoveryKey": "RK-xxxxxxxxxxxxxxxxxxxxxxxx"
}

Xem Mailbox

GET/mailboxes/:address

Lấy thông tin mailbox. address là địa chỉ email đầy đủ, URL-encoded.

curl

curl https://vibecoder.io.vn/mailboxes/otp-test%40vibecoder.io.vn \
  -H "Authorization: Bearer tm_YOUR_KEY"

Liệt kê tin nhắn

GET/mailboxes/:address/messages

Lấy danh sách tất cả tin nhắn trong mailbox, sắp xếp mới nhất trước.

curl

curl https://vibecoder.io.vn/mailboxes/otp-test%40vibecoder.io.vn/messages \
  -H "Authorization: Bearer tm_YOUR_KEY"

200

json
{
  "mailbox": { ... },
  "messages": [
    {
      "id": "abc123",
      "from": "noreply@example.com",
      "to": "otp-test@vibecoder.io.vn",
      "subject": "Your OTP code",
      "receivedAt": "2025-01-01T12:05:00.000Z"
    }
  ]
}

Chi tiết tin nhắn

GET/messages/:id

Lấy nội dung đầy đủ của tin nhắn (text, HTML, headers).

curl

curl https://vibecoder.io.vn/messages/abc123 \
  -H "Authorization: Bearer tm_YOUR_KEY"

200

json
{
  "message": {
    "id": "abc123",
    "from": "noreply@example.com",
    "to": "otp-test@vibecoder.io.vn",
    "subject": "Your OTP code",
    "text": "Your code is 482910",
    "html": "<p>Your code is <b>482910</b></p>",
    "receivedAt": "2025-01-01T12:05:00.000Z"
  }
}

Gia hạn Mailbox

POST/mailboxes/:address/extend

Kéo dài thời hạn sống của mailbox.

Tham số	Kiểu	Bắt buộc	Mô tả
ttlMinutes	number	Yêu cầu	Thời hạn mới (phút), từ 1 đến 1440.

curl
curl -X POST https://vibecoder.io.vn/mailboxes/otp-test%40vibecoder.io.vn/extend \
  -H "Authorization: Bearer tm_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttlMinutes": 120}'

Xoá Mailbox

DELETE/mailboxes/:address

Xoá vĩnh viễn mailbox và toàn bộ tin nhắn bên trong.

curl

curl -X DELETE https://vibecoder.io.vn/mailboxes/otp-test%40vibecoder.io.vn \
  -H "Authorization: Bearer tm_YOUR_KEY"

204 Thành công (không có body)

Email của tôi

GET/api/my/mailboxes

Lấy danh sách tất cả mailbox của user đang đăng nhập. Yêu cầu cookie session (không cần Bearer token).

🔒 Yêu cầu đăng nhập (cookie session). Truy cập Dashboard để dùng giao diện đồ hoạ.

200

json
{
  "mailboxes": [
    {
      "address": "test@vibecoder.io.vn",
      "label": "test",
      "createdAt": "2025-01-01T12:00:00.000Z",
      "expiresAt": "2025-01-01T13:00:00.000Z",
      "recoveryKey": "RK-xxxx...",
      "active": true
    }
  ]
}

Xem inbox của tôi

GET/api/my/mailboxes/:address/messages

Lấy tin nhắn trong mailbox thuộc về user đang đăng nhập. Chỉ xem được mailbox do chính mình tạo.

200

json
{
  "mailbox": { ... },
  "messages": [
    { "id": "...", "from": "...", "subject": "...", "receivedAt": "..." }
  ]
}

Chi tiết thư của tôi

GET/api/my/messages/:id

Xem nội dung đầy đủ của tin nhắn. Chỉ xem được thư thuộc mailbox của mình.

Xóa mailbox của tôi

DELETE/api/my/mailboxes/:address

Xóa vĩnh viễn mailbox mà bạn đã tạo. Chỉ xóa được mailbox thuộc về tài khoản của bạn.

204 Thành công

Danh sách domain

GET/api/domains

Lấy danh sách tất cả domain có sẵn và domain đang pending (không cần xác thực).

curl

curl https://vibecoder.io.vn/api/domains

200

json
{
  "domains": ["vibecoder.io.vn", "luuvan.site", ...],
  "pendingDomains": ["locpnv.site", ...]
}

⚠ Domain trong pendingDomains chưa kích hoạt DNS — email gửi đến sẽ không nhận được. Tránh tạo mailbox với domain pending.