Mở hộp thư trong ứng dụng Mail

Các ứng dụng panel HiTechCloud (User, Admin, Reseller) có thao tác Open in Mail. Thao tác này mở ứng dụng HiTechCloud Mail ở trạng thái đã đăng nhập vào một trong các hộp thư của tài khoản, không cần mật khẩu hộp thư và không đặt mật khẩu hay token dài hạn vào liên kết.

Ứng dụng panel yêu cầu panel cấp một vé thư cho một hộp thư.
Panel yêu cầu webmail cấp vé, qua một lời gọi có chữ ký trên địa chỉ loopback riêng của máy chủ, và trả vé về kèm một liên kết dựng sẵn.
Ứng dụng mở liên kết. Mail đổi vé lấy một phiên tại webmail (POST /api/auth/ticket, xem docs/APP_SSO_PUSH.md của webmail).

Vé tồn tại 30 giây và dùng được một lần. Nếu hộp thư bật xác minh hai bước, vé không bỏ qua bước đó: Mail quay về dùng mật khẩu và bước thứ hai.

`POST /api/emails/mail-ticket/{mailbox}`

Gửi Bearer token từ POST /api/login và không có body.

curl -X POST https://panel.example.com:2083/api/emails/mail-ticket/info@example.com \
  -H "Authorization: Bearer $TOKEN"

{
  "ticket": "v1.aW5mb0BleGFtcGxlLmNvbQ.1760000030000.k3J9xQ2mP7vN4aTz.0f3a...64 hex...",
  "expires_at": 1760000030,
  "expires_in": 30,
  "server": "mail.example.com",
  "url": "hitechcloud-mail://open?server=mail.example.com&ticket=v1.aW5mb0BleGFtcGxlLmNvbQ.1760000030000.k3J9xQ2mP7vN4aTz.0f3a...&user=info%40example.com"
}

Trường	Ý nghĩa
`ticket`	`v1.<base64url(mailbox)>.<expiresMs>.<nonce>.<hexSig>`, đúng như webmail đã cấp. Là thông tin xác thực dạng bearer cho hộp thư: chỉ gửi qua HTTPS, không bao giờ ghi nhật ký hay lưu lại.
`expires_at`	Thời điểm hết hiệu lực, tính bằng giây Unix.
`expires_in`	Số giây còn lại khi câu trả lời được tạo.
`server`	Host của webmail (kèm cổng, nếu có): nơi Mail đổi vé. Không phải host của panel.
`url`	`hitechcloud-mail://open?server=<server>&ticket=<ticket>&user=<mailbox>`, đã mã hoá dạng form. Mở nguyên trạng.

Ai được yêu cầu, và khi nào bị từ chối

Trạng thái	`error` trong body	Lý do
403	`A mail sign-in ticket cannot be issued with an MCP token.`	Token MCP là thông tin xác thực lâu dài cho agent; chỉ token đăng nhập mới được tạo vé hộp thư.
403	`This account is suspended.`	Tài khoản bị tạm ngưng không thể mở hộp thư của mình.
403	`Your plan does not include webmail.`	Gói không có tính năng webmail (cũng cần tính năng Email).
403	`You do not own <domain>.` / `That is not an email address.`	Địa chỉ không thuộc tên miền mà tài khoản sở hữu.
404	`There is no mailbox <address> on this server.`	Địa chỉ không phải một trong các hộp thư của tài khoản.
429	`Too many requests. Please try again later.`	Hơn 10 lời gọi một phút từ một tài khoản (`mail_ticket_ratelimit` trong cấu hình panel thay đổi con số này).
503	`Webmail is not installed on this server.` và các thông báo tương tự	Không có webmail, không có bí mật chuyển giao, hoặc webmail không trả lời.
502	câu thông báo riêng của webmail, hoặc `The mail server's ticket was not usable (...)`	Webmail từ chối (ví dụ nó không do panel này quản lý), hoặc trả về thứ không phải vé hợp lệ cho hộp thư này.

Mỗi vé đều được kiểm tra trước khi chuyển đi: đúng dạng ở trên, đúng hộp thư này, thời hạn trong vòng 60 giây, nonce từ 16 đến 64 ký tự an toàn cho URL và chữ ký hex 64 ký tự.

Mỗi vé được cấp đều được ghi vào nhật ký hoạt động của tài khoản (issued a one-time Mail app sign-in ticket for <mailbox>). Bản thân vé không bao giờ được ghi nhật ký. MCP client không thấy endpoint này.

Cách ly thư rác

Nhật ký thư

Trang này có hữu ích không?