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ờ. Để kết nối tool lâu dài: đăng nhập web, dùng khung API của bạn ngay tại trang tạo mail, tạo key mới rồi sao chép API key cố định. Key này giữ nguyên, không tự hết hạn và dùng được qua Authorization: Bearer hoặc X-API-Key. Đăng xuất web không thu hồi key cố định; key bị thu hồi khi chủ tài khoản bấm Xóa key. API key cũ vẫn được giữ. Token do endpoint /login cấp là token phiên có hạn 24 giờ.

API key cố định: tạo nhiều key và xóa từng key

Đăng nhập tài khoản, dùng khung API của bạn ngay trên trang tạo mail, đặt tên rồi bấm Tạo key. Key hiện đầy đủ và có nút sao chép trong danh sách cá nhân. Mỗi key hoạt động độc lập, không tự hết hạn. Bấm Xóa key để thu hồi ngay; tạo key mới không làm key khác mất hiệu lực.

Tool không được nhúng sẵn API key. Theo lựa chọn mới, app có thể nhớ key người dùng đã nhập trong cấu hình riêng; trang Playground chỉ giữ key trong trang đang mở. API quản trị được tạo mail và đọc liên tục, không áp dụng cooldown hay hạn mức theo thời gian của ứng dụng. Tốc độ vẫn phụ thuộc tài nguyên máy chủ và hạn mức nền tảng Cloudflare. Hộp thư vẫn hết hạn sau 600 giây và mở lại bằng email + mật khẩu.

Quản lý key qua phiên web của chính tài khoản: GET /api/v1/keys, POST /api/v1/keys JSON {"name":"Máy tính cá nhân"}, và POST /api/v1/delete-key JSON {"id":"KEY_ID"}. POST cần cookie đăng nhập và header X-CSRF-Token. API key không có quyền tạo hoặc xóa các API key khác. Database lưu hash để xác thực. Bản đầy đủ được giữ trong thư mục riêng của máy chủ (ngoài web, quyền 600) để chủ tài khoản xem và sao chép. Admin chỉ xem key của tài khoản quản trị; không xem hay xóa key của người dùng. Phiên web người dùng chỉ xem và xóa key của mình. Bearer API key không có quyền xem danh sách key. Các key cũ chỉ còn hash không thể khôi phục chuỗi đầy đủ, cần tạo key mới nếu không còn bản đã lưu.

Tài khoản người dùng riêng

Admin đăng nhập web, chọn Người dùng để tạo tài khoản, đặt lại mật khẩu hoặc khóa/mở tài khoản. Người dùng đăng nhập bằng username và mật khẩu được cấp, tự tạo mail trên hai domain và tạo/xem/sao chép/xóa API key của mình. Họ chỉ truy cập hộp thư do chính tài khoản tạo; admin quản lý toàn bộ. Hộp thư cũ chưa gán người dùng vẫn thuộc quyền quản trị.

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

{"username":"thanhvien01","password":"USER_PASSWORD"}

Phản hồi có role: "user", user_id, username và token phiên có hiệu lực 30 ngày. API key cố định của người dùng sử dụng cùng các endpoint tạo mail, danh sách thư, đọc thư, OTP và public_api.php; quyền luôn giới hạn trong tài khoản sở hữu key. Key không tự hết hạn và không có cooldown tạo mail. Quản lý key cần đăng nhập web và CSRF, không chấp nhận Bearer key. Playground lấy đúng key thuộc tài khoản đang đăng nhập.

Đặt lại mật khẩu người dùng làm các phiên web và token đăng nhập cũ hết hiệu lực, giữ nguyên API key cố định. Khóa tài khoản chặn cả đăng nhập, phiên cũ và API key; mở lại cho phép dùng key chưa bị xóa. Xóa key thu hồi vĩnh viễn key đó. Người biết email và mật khẩu hộp thư vẫn có thể dùng chức năng khôi phục hộp thư riêng; khóa tài khoản người dùng không đổi mật khẩu từng hộp thư.

API quản lý người dùng chỉ dành cho phiên web admin + X-CSRF-Token:

GET /api/v1/users
POST /api/v1/users
{"username":"thanhvien01","password":"OPTIONAL_PASSWORD"}

POST /api/v1/update-user
{"id":"USER_ID","change":"enabled","enabled":false}

POST /api/v1/update-user
{"id":"USER_ID","change":"password","password":"NEW_PASSWORD"}

Bỏ trống password để tự sinh. Mật khẩu 8–72 byte; username 3–32 ký tự gồm chữ, số, dấu chấm, gạch dưới, gạch ngang, bắt đầu bằng chữ hoặc số, không dùng tên admin. Tạo thành công trả 201 và mật khẩu để lưu một lần; trùng tên trả 409, truy cập ngoài quyền trả 403. API danh sách không trả hash hay mật khẩu. Ghi chú: dấu gạch chỉ được dùng trong username đăng nhập, tên email mới vẫn chỉ gồm chữ và số.

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

Trang chủ: https://bflive.sbs. Nhận địa chỉ [email protected] và [email protected]. 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":"[email protected]","username":"[email protected]","password":"GENERATED_PASSWORD","created":true}

Bỏ name để sinh tên dạng chữ/số + apqt + chữ/số, không có dấu gạch. Tên tự nhập cũng chỉ gồm chữ và số. Bỏ domain, truyền chuỗi rỗng hoặc domain="random" để chọn ngẫu nhiên giữa các domain đang bật. Truyền tên domain cụ thể để chọn cố định. 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":"[email protected]","password":"MAIL_PASSWORD"}

{"ok":true,"role":"mailbox","address":"[email protected]","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":"[email protected]","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":"[email protected]","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à SMTP relay gửi thư đã cấu hình; 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

400: JSON không hợp lệ · 405: sai phương thức · 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.

API admin dùng key/token không áp dụng giới hạn 600 yêu cầu/phút hay cooldown tạo mail. Phiên web và token mailbox: 600 yêu cầu/phút/IP; đăng nhập/restore: 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.

9. API tương thích public_api.php và Playground

Mở API Playground để thử request ngay trên web. Dùng header X-API-Key: YOUR_API_KEY; key quản trị cũ hoặc Bearer token đăng nhập đều được chấp nhận. Tham số api_key trong URL cũng được hỗ trợ cho client cũ, nhưng nên dùng header để tránh lộ key khi chia sẻ URL.

uid là số ổn định của thư. id và position là vị trí hiện tại, bắt đầu từ 1; vị trí thay đổi khi thêm hoặc xóa thư. Khi xóa nên dùng uid. msgno là alias vị trí để tương thích, không phải IMAP msgno. Nội dung được trả qua body_text; body_html rỗng vì web không thực thi HTML nhận được.

Hết 10 phút, cả API tương thích và API v1 đều trả 410 khi đọc hộp thư. Khôi phục không cần key quản trị nhưng bắt buộc đúng email và mật khẩu. Không dùng API xóa thư để gia hạn hộp thư. Xóa thư chỉ ảnh hưởng hộp thư đang được cấp quyền.

curl "https://bflive.sbs/public_api.php?action=create&domain=thichsex.com" \
  -H "X-API-Key: YOUR_API_KEY"

Endpoint gốc POST /api/v1/delete-message nhận JSON {"address":"[email protected]","id":"MESSAGE_ID"}. API tương thích trả lỗi theo trường success:false, giữ các giới hạn quyền truy cập và thời hạn như API v1.

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

Cài requests. Nhập API key khi chạy, chỉ giữ trong RAM; không ghi key vào mã nguồn hay tệp cấu hình. Lưu mật khẩu hộp thư ở nơi riêng tư nếu cần mở lại.

API cá nhân trên trang tạo mail

Đăng nhập rồi dùng khung API của bạn ngay cạnh phần tạo mail: tạo key, sao chép địa chỉ API, xem key và ví dụ đọc OTP. Mỗi tài khoản chỉ xem, sao chép và xóa key của chính mình. Admin chỉ thấy key của tài khoản quản trị, không xem hoặc xóa key cá nhân của người dùng. Quyền sở hữu được kiểm tra trên máy chủ, không nhận user_id từ trình duyệt để chuyển chủ key.