Open a mailbox in the Mail app
The HiTechCloud panel apps (User, Admin, Reseller) have an Open in Mail action. It opens the HiTechCloud Mail app already signed in to one of the account's mailboxes, without the mailbox password and without putting a password or a long-lived token in a link.
- The panel app asks the panel for a mail ticket for one mailbox.
- The panel asks the webmail for a ticket, over a signed call on the server's own loopback address, and returns it with a ready-made link.
- The app opens the link. Mail trades the ticket for a session at the webmail
(
POST /api/auth/ticket, see the webmail'sdocs/APP_SSO_PUSH.md).
A ticket lives 30 seconds and works once. If the mailbox has two-step verification on, the ticket does not skip it: Mail falls back to the password and the second step.
POST /api/emails/mail-ticket/{mailbox}
Send the Bearer token from POST /api/login and no 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"
}
| Field | Meaning |
|---|---|
ticket | v1.<base64url(mailbox)>.<expiresMs>.<nonce>.<hexSig>, as the webmail issued it. A bearer credential for the mailbox: send it only over HTTPS, never log or store it. |
expires_at | When it stops working, in Unix seconds. |
expires_in | Seconds left when the answer was made. |
server | The webmail's host (and port, if it has one): where Mail redeems the ticket. Not the panel's host. |
url | hitechcloud-mail://open?server=<server>&ticket=<ticket>&user=<mailbox>, form-encoded. Open it as it is. |
Who may ask, and when it is refused
| Status | Body error | Why |
|---|---|---|
| 403 | A mail sign-in ticket cannot be issued with an MCP token. | An MCP token is a standing credential for an agent; only a sign-in token may mint a mailbox ticket. |
| 403 | This account is suspended. | Suspended accounts cannot open their mailboxes. |
| 403 | Your plan does not include webmail. | The plan lacks the webmail feature (the Emails feature is needed too). |
| 403 | You do not own <domain>. / That is not an email address. | The address is not on a domain the account owns. |
| 404 | There is no mailbox <address> on this server. | The address is not one of the account's mailboxes. |
| 429 | Too many requests. Please try again later. | More than 10 calls a minute from one account (mail_ticket_ratelimit in the panel configuration changes the figure). |
| 503 | Webmail is not installed on this server. and the like | No webmail, no hand-off secret, or the webmail did not answer. |
| 502 | the webmail's own sentence, or The mail server's ticket was not usable (...) | The webmail refused (for example it is not managed by this panel), or answered with something that is not a valid ticket for this mailbox. |
Every ticket is checked before it is handed on: the form above, this mailbox, an expiry within 60 seconds, a nonce of 16 to 64 URL-safe characters and a 64-character hex signature.
Each issued ticket is written to the account's activity log
(issued a one-time Mail app sign-in ticket for <mailbox>). The ticket itself
is never logged. MCP clients do not see this endpoint.