Mail tạm. Lưu thông tin.
Mở lại khi cần.

1. Đăng nhập quản trị và lấy token

POST /api/v1/login
Content-Type: application/json

{"username":"APQT","password":"ADMIN_PASSWORD"}

{"ok":true,"role":"admin","token":"ADMIN_TOKEN","token_type":"Bearer","expires_in":86400}

Header cho API: Authorization: Bearer ADMIN_TOKEN. Token admin có hiệu lực 24 giờ. Trên web, đăng nhập rồi sao chép token ở mục Token API quản trị. Token mới cấp có hạn 24 giờ. API key cố định đã có từ bản trước vẫn được giữ để tương thích tool cũ.

2. Domain và thời hạn hộp thư

Trang chủ: https://mail.apqt.io.vn. Chỉ nhận địa chỉ ten@bflive.sbs. Hộp thư có hiệu lực 600 giây từ lúc tạo hoặc mở lại bằng email + mật khẩu. Không tự gia hạn khi đọc thư.

Hết 10 phút, địa chỉ tự ẩn khỏi danh sách và API đọc thư trả 410. Dữ liệu không bị xóa. Gọi POST /restore bằng email + mật khẩu để mở lại cùng thư cũ thêm 10 phút. Có thể tạo địa chỉ ngẫu nhiên mới bất cứ lúc nào. Tên cũ được giữ cho chủ cũ; tạo trùng trả 409, tránh người khác đọc được thư cũ.

3. Tạo mail tạm kèm mật khẩu

POST /api/v1/addresses
Authorization: Bearer ADMIN_TOKEN
Content-Type: application/json

{"domain":"bflive.sbs","name":"demo"}

{"address":"demo@bflive.sbs","username":"demo@bflive.sbs","password":"GENERATED_PASSWORD","created":true}

Bỏ name để sinh tên ngẫu nhiên. Domain mặc định là bflive.sbs. Có thể truyền password riêng (8–72 byte); bỏ trống để tự sinh. Lưu email + mật khẩu ngay, mật khẩu chỉ được trả khi tạo/đặt lại. Tên trùng trả 409, không ghi đè mật khẩu hoặc thư cũ.

4. Khôi phục hộp thư tạm và thư cũ

POST /api/v1/restore
Content-Type: application/json

{"username":"demo@bflive.sbs","password":"MAIL_PASSWORD"}

{"ok":true,"role":"mailbox","address":"demo@bflive.sbs","token":"MAIL_TOKEN","token_type":"Bearer","expires_in":2592000}

Không cần token admin. Token mailbox có hiệu lực 30 ngày, chỉ truy cập đúng hộp thư đó; quyền đọc thư vẫn bị chặn khi hộp thư hết 10 phút. Mở lại bằng mật khẩu sẽ gia hạn hộp thư thêm 10 phút. POST /login cũng chấp nhận email + mật khẩu mail. Trên web, nhập email và mật khẩu ở màn hình đăng nhập để mở lại. Khôi phục ở đây là mở lại dữ liệu đã lưu, không phục hồi dữ liệu đã mất do xóa database.

5. Đọc thư, nội dung và mã OTP

GET /api/v1/messages?limit=100&offset=0
Authorization: Bearer MAIL_TOKEN

GET /api/v1/message?id=MESSAGE_ID
Authorization: Bearer MAIL_TOKEN

GET /api/v1/otp?since=1793400000
Authorization: Bearer MAIL_TOKEN

{"address":"demo@bflive.sbs","otp":"123456","message_id":"...","received":1793400100}

Token mailbox tự xác định địa chỉ. Admin thêm address=demo%40bflive.sbs vào query. messages hỗ trợ since (Unix giây), limit 1–100 và offset để phân trang. otp trả otp:null khi chưa có mã. Mã gợi ý là 4–8 chữ số trong tiêu đề/nội dung, cần đối chiếu người gửi và thời gian. Nội dung thư trả văn bản; không thực thi HTML/JavaScript trong thư.

6. Quên mật khẩu mail

POST /api/v1/setpassword
Authorization: Bearer ADMIN_TOKEN
Content-Type: application/json

{"address":"demo@bflive.sbs","password":"NEW_MAIL_PASSWORD"}

Chỉ admin đặt lại. Bỏ password để tự sinh. Giữ nguyên thư; thu hồi mọi token và phiên cũ của mailbox đó.

7. Khôi phục mật khẩu quản trị web

POST /api/v1/forgot-password
Content-Type: application/json

{"username":"APQT"}

Trả 202 với thông báo chung. Liên kết được gửi tới email khôi phục đã cấu hình trước trên máy chủ, không gửi tới địa chỉ tùy ý trong yêu cầu. Máy chủ cần cấu hình email khôi phục và khả năng gửi mail hosting; nếu chưa cấu hình, API trả 503.

POST /api/v1/reset-password
Content-Type: application/json

{"token":"RESET_TOKEN_FROM_EMAIL","password":"NEW_ADMIN_PASSWORD"}

Token trong email có hiệu lực 15 phút, chỉ dùng một lần. Sau đặt lại, toàn bộ phiên/token quản trị cũ hết hiệu lực. Có giao diện Quên mật khẩu quản trị ngay trên trang đăng nhập. API không trả token khôi phục trong phản hồi.

8. Phiên đăng nhập, trạng thái và lỗi

401: sai thông tin/hết hạn · 403: thiếu quyền/CSRF · 404: không tìm thấy · 409: trùng tên/DNS chưa đúng · 415: cần JSON · 422: dữ liệu sai · 410: hộp thư hết hạn, cần restore · 429: quá giới hạn · 503: dịch vụ hoặc cấu hình chưa sẵn sàng.

Giới hạn chung 600 yêu cầu/phút/IP; đăng nhập 12 lần/phút; gửi email khôi phục 3 lần/phút. Khi 429, đợi theo header Retry-After (60 giây). Cookie web dùng HttpOnly/Secure/SameSite, yêu cầu thay đổi dữ liệu có X-CSRF-Token. Tool dùng Bearer token không cần CSRF.

Ví dụ Python: tạo, mở lại và đợi OTP

Cài requests. Đặt token quản trị vào biến môi trường APQT_MAIL_TOKEN. Lưu mật khẩu mail ở nơi riêng tư.