Dùng API key của tài khoản để lấy mailbox, đọc OTP, theo dõi lịch sử thuê.
http://127.0.0.1:2012Lấy API key tại Hồ sơ. Gửi key trong header X-API-Key hoặc Authorization: Bearer ở mọi request API V1.
curl http://127.0.0.1:2012/api/v1/me \
-H "X-API-Key: mrk_your_api_key"const response = await fetch(
"http://127.0.0.1:2012/api/v1/me",
{ headers: { "X-API-Key": apiKey } }
);
const data = await response.json();/api/servicesTrả về các dịch vụ đang được frontend sử dụng. Giá trị services[].id chính là service_id cần gửi khi gọi API thuê mail.
curl http://127.0.0.1:2012/api/services \
-H "X-API-Key: mrk_your_api_key" \
-H "Accept: application/json"{
"services": [{
"id": "icloud-facebook",
"name": "Facebook",
"code": "FACEBOOK",
"price": 500,
"stock": 12,
"mailbox_type": "iCloud Mail OTP",
"available": true
}]
}Chọn dịch vụ có available: true và stock > 0, lấy services[].id, rồi truyền nguyên giá trị đó vào POST /api/orders/rent. Endpoint /api/products chỉ là compatibility path của frontend cũ, không được xem là alias backend đã xác nhận.
Các endpoint bên dưới dùng API key của tài khoản. Gửi X-API-Key: mrk_your_api_key hoặc Authorization: Bearer mrk_your_api_key, kèm Content-Type: application/json.
/api/orders/rentTạo một đơn thuê mới từ service_id. Lấy service ID từ danh sách dịch vụ mà hệ thống cung cấp.
curl -X POST http://127.0.0.1:2012/api/orders/rent \
-H "X-API-Key: mrk_your_api_key" \
-H "Content-Type: application/json" \
-d '{"service_id":"icloud-facebook"}'{
"balance": 4500,
"order": {
"id": 15,
"email": "mail@example.com",
"price": 500,
"status": "Pending OTP"
}
}Sau khi thuê thành công, dùng order ID để theo dõi OTP/lịch sử. Số dư trong response là số dư mới sau giao dịch.
/api/orders/rerentTạo đơn thuê lại từ một đơn cũ bằng rental_id. Backend quyết định đơn nào đủ điều kiện thuê lại.
curl -X POST http://127.0.0.1:2012/api/orders/rerent \
-H "Authorization: Bearer mrk_your_api_key" \
-H "Content-Type: application/json" \
-d '{"rental_id":15}'{
"balance": 4150,
"order": {
"id": 16,
"email": "mail@example.com",
"price": 350,
"status": "Pending OTP"
}
}Dùng rental_id từ lịch sử đơn thuê. Giá và điều kiện thuê lại do backend cấu hình; không giả định một tỷ lệ hoặc thời hạn cố định ở client.
/api/orders/aliasTạo alias từ một đơn thuê hiện có bằng rental_id. Backend sinh mailbox alias và xác thực điều kiện của đơn gốc.
curl -X POST http://127.0.0.1:2012/api/orders/alias \
-H "X-API-Key: mrk_your_api_key" \
-H "Content-Type: application/json" \
-d '{"rental_id":15}'{
"balance": 4100,
"order": {
"id": 17,
"email": "alias@example.com",
"price": 50,
"status": "Pending OTP"
}
}Trong lịch sử đơn, alias có thể kèm source_mailbox để liên kết với mailbox gốc. Chỉ backend mới xác định được loại đơn nào có thể tạo alias.
/api/v1/meTrả về tên đăng nhập, email, họ tên và số dư xu hiện có.
curl http://127.0.0.1:2012/api/v1/me \
-H "X-API-Key: mrk_your_api_key"{
"user": {
"username": "phatchau036",
"email": "user@example.com",
"full_name": "Phat Chau",
"balance": 5000
}
}/api/v1/mail?mailbox=mail@example.comKhông truyền mailbox để lấy tóm tắt OTP từ các đơn thuê. Truyền mailbox để đọc nội dung mail từ IMAP.
curl "http://127.0.0.1:2012/api/v1/mail?mailbox=mail@example.com" \
-H "Authorization: Bearer mrk_your_api_key"{
"mailbox": "mail@example.com",
"messages": [{
"uid": "42",
"subject": "Your verification code",
"otp": "123456",
"date": "Fri, 22 Aug 2026 ..."
}]
}/api/v1/mailboxesLấy các mailbox thuộc tài khoản hiện tại và thông tin dịch vụ đã dùng.
curl http://127.0.0.1:2012/api/v1/mailboxes \
-H "X-API-Key: mrk_your_api_key"{
"mailboxes": [{
"mailbox": "mail@example.com",
"note": "iCloud OTP",
"created_at": "22/08/2026 08:23"
}]
}/api/v1/mail-history?mailbox=mail@example.comLọc theo một mailbox bằng query mailbox hoặc bỏ query để lấy toàn bộ lịch sử của tài khoản.
curl "http://127.0.0.1:2012/api/v1/mail-history" \
-H "X-API-Key: mrk_your_api_key"{
"history": [{
"mailbox": "mail@example.com",
"service_name": "Facebook",
"status": "completed"
}]
}/api/v1/rentalsTrả về các đơn thuê, trạng thái và OTP nếu đã nhận được.
curl http://127.0.0.1:2012/api/v1/rentals \
-H "X-API-Key: mrk_your_api_key"{
"rentals": [{
"id": 15,
"service": "Facebook",
"email": "mail@example.com",
"otp": "123456",
"status": "completed"
}]
}{ "error": "Valid API key required..." }{ "error": "Mailbox or rental not found." }Tùy cấu hình backend, request thiếu hoặc sai service_id/rental_id có thể trả 400; không đủ số dư có thể trả 402; đơn không đủ điều kiện có thể trả 409 hoặc 422; backend tạm thời không khả dụng có thể trả 502. Luôn đọc trường error trong JSON để hiển thị thông báo.