SCOOPY / REST API

Tích hợp đọc mail vào tool.

Đọc Hotmail / Outlook bằng refresh token. Gửi JSON qua HTTPS, không đặt thông tin tài khoản trong URL. API chỉ đọc thư.

1. Đọc một lần, không giữ phiên

POST /api/mail/read · thêm header X-Scoopy-Client: mail-web.

curl https://scoopyvn.shop/api/mail/read   -H "Content-Type: application/json"   -H "X-Scoopy-Client: mail-web"   --data '{"email":"your-mail@hotmail.com","refreshToken":"YOUR_TOKEN","clientId":"YOUR_CLIENT_ID","folder":"inbox","page":1}'

Trả về {email, messages, folder, page, hasMore}. Mỗi thư có id, subject, from, fromAddress, date, preview, unread. Gửi thêm messageId trong JSON để lấy nội dung thư, gồm text, html, codes. Thư mục: inbox hoặc junk; mỗi trang tối đa 20 thư. mode là auto (mặc định), graph hoặc imap.

2. Đọc nhiều lần qua mã kết nối

Giảm số lần trao đổi token khi tool cần làm mới hộp thư.

POST /api/mail/connect
{"email":"your-mail@hotmail.com","refreshToken":"YOUR_TOKEN","clientId":"YOUR_CLIENT_ID"}

// Phản hồi: {connectionId, email, expiresAt, messages, ...}
// Các bước dưới thêm hai header:
// X-Scoopy-Client: mail-web
// Authorization: Bearer CONNECTION_ID
GET /api/mail/messages?folder=inbox&page=1
GET /api/mail/messages/MESSAGE_ID?folder=inbox
DELETE /api/mail/session

Mỗi mail có mã riêng; kết nối mail mới không đóng mail cũ. Mã hết hạn sau tối đa 20 phút hoặc khi access token hết hạn. Nếu nhận 401 session_expired, gọi lại /connect. Tool tự giữ refresh token; server chỉ giữ access token tạm thời trong RAM.

3. Kiểm tra hàng loạt

POST /api/mail-check/start
{"accounts":[{"email":"your-mail@hotmail.com","refreshToken":"YOUR_TOKEN","clientId":"YOUR_CLIENT_ID"}]}

// Phản hồi HTTP 202: {jobId, total, running, ...}
// Thêm X-Scoopy-Client: mail-web và X-Scoopy-Job: JOB_ID
GET /api/mail-check/job
DELETE /api/mail-check/job

Tối đa 500 mail/đợt, 4 đợt/10 phút/IP. Gọi trạng thái cách nhau ít nhất 2 giây; kết quả tự xóa sau 15 phút khi hoàn tất. Trạng thái: live, auth_error, unknown, invalid. LIVE chỉ xác nhận quyền mở hộp thư ở thời điểm kiểm tra.

Giới hạn & lỗi

Đọc trực tiếp hoặc tạo kết nối: tổng 30 lần/10 phút/IP. Đọc bằng mã kết nối: 45 lần/phút/mã. Có giới hạn đồng thời cho toàn hệ thống; gặp HTTP 429 hoặc 503 hãy chờ rồi thử lại, tránh gửi dồn.

{"error":"Mô tả lỗi an toàn","code":"invalid_grant"}

400: dữ liệu sai · 401: token hoặc kết nối hết hạn · 403: thiếu quyền/header · 429: quá nhanh · 502/503: tạm thời chưa kết nối được. Mã có thể là invalid_grant, invalid_client, permission_denied, imap_auth_failed, session_expired. Không tự kết luận email chết khi nhận lỗi xác thực.

Không cần API key Scoopy ở phiên bản này; bắt buộc có OAuth hợp lệ của chính hộp thư. Không gửi mật khẩu hoặc email khôi phục vì API không sử dụng hai trường đó.