API REFERENCE

Tích hợp MailFlow

API sử dụng JSON và Bearer token. Sau khi nhận Gmail, bạn có thể lấy thư hoặc báo email đã được dùng.

Xác thực

Thêm API key vào header của mọi request công khai:

Authorization: Bearer YOUR_API_KEY

POST

/v1/mailboxes

Cấp một Gmail chưa từng được dùng cho dịch vụ chỉ định trên toàn hệ thống.

curl -X POST https://api.rentotps.com/v1/mailboxes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service":"instagram"}'

Phản hồi

{
  "success": true,
  "email": "example@gmail.com",
  "token": "transaction_token",
  "expires_in": 600
}

POST

/v1/transactions/check

Kiểm tra xem giao dịch đã nhận được thư hay chưa.

curl -X POST https://api.rentotps.com/v1/transactions/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token":"transaction_token"}'

Kết quả thành công

{
  "success": true,
  "code": "194748"
}

Kết quả chưa có thư hoặc gặp lỗi

{
  "success": "fail",
  "message": "not mail yet"
}

Mọi lỗi giao dịch đều chỉ có hai trường success và message. Giá trị message đầy đủ:

Trường hợp	Response JSON
Chưa có thư	`{"success":"fail","message":"not mail yet"}`
Không kết nối được IMAP	`{"success":"fail","message":"Error. Please use another email"}`
Token hết hạn	`{"success":"fail","message":"Token expried"}`
Token không tồn tại	`{"success":"fail","message":"token not found"}`
Email đã được báo sử dụng	`{"success":"fail","message":"mailbox was marked used by user report"}`
Thư không có mã 6 số	`{"success":"fail","message":"không tìm thấy code 6 số trong thư"}`
Lỗi xử lý thư khác	`{"success":"fail","message":"không thể lấy code từ mail này, vui lòng gọi mail khác"}`

API chỉ trả mã gồm đúng 6 chữ số; không trả người gửi, tiêu đề, HTML hoặc nội dung thư.

POST

/v1/transactions/report-used

Báo Gmail vừa nhận đã được sử dụng cho dịch vụ. IMAP sẽ đóng ngay, Gmail được đánh dấu riêng là reported_used và không tính lượt thành công.

curl -X POST https://api.rentotps.com/v1/transactions/report-used \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token":"transaction_token"}'

GET

Dùng trực tiếp trên URL

Có thể gọi trực tiếp trên thanh địa chỉ hoặc phần mềm chỉ hỗ trợ GET.

Lấy Gmail mới

https://rentotps.com/getmail/YOUR_API_KEY?sender=instagram

Kiểm tra và lấy code

https://rentotps.com/getcode/TRANSACTION_TOKEN?apikey=YOUR_API_KEY

Báo email đã bị sử dụng

https://rentotps.com/reportused/TRANSACTION_TOKEN?apikey=YOUR_API_KEY

URL báo đã dùng sẽ đóng IMAP ngay, đánh dấu Gmail–dịch vụ đã sử dụng và không tính lượt thành công. Kết quả JSON và cơ chế xử lý giống API POST.

Quy tắc hoạt động

Token chờ thư có hiệu lực trong 10 phút.
Sau lần lấy code thành công đầu tiên, token tiếp tục trả cùng code trong 3 phút rồi tự vô hiệu hóa.
Gọi lại cùng token trong 3 phút không tăng thêm lượt sử dụng.
Chỉ thư đến sau lúc cấp token mới được chấp nhận.
Sender có thể là chuỗi như instagram; hệ thống sẽ khớp địa chỉ như noreply@instagram.com.
Lượt sử dụng chỉ tăng khi code được trả thành công lần đầu.
Báo email đã dùng không tăng lượt thành công nhưng vẫn khóa cặp Gmail và dịch vụ đó trên toàn hệ thống.
Riêng Instagram: khi toàn bộ Gmail khả dụng đã nhận code thành công, hệ thống mở chu kỳ mới và cho phép dùng lại nhóm Gmail đó từ đầu.
Mail lỗi IMAP và mail do khách báo đã sử dụng không được đưa vào chu kỳ Instagram mới.
Một Gmail đã dùng cho dịch vụ khác sẽ không được cấp lại cho dịch vụ đó, bất kể người dùng nào gọi API.
Một thư không được trả trùng ở giao dịch khác.