## POST /api/v2/shared-hosting/{accountId}/email-accounts/{address}/actions/sso

**Create a webmail login link**

Creates a one-time webmail login link for one mailbox. The mail can then be read without the mailbox password. Open the link right away in the browser of the person who reads the mail. Do not store it. To open the control panel of the whole account instead, use `POST /api/v2/shared-hosting/{accountId}/actions/sso`. The mailbox domain must be on the account. An account on Hostup's previous hosting platform returns 409 `account_not_eligible_cpanel`.

### Related Endpoints

- `POST /api/v2/shared-hosting/{accountId}/email-accounts/{address}/actions/mail-profile-link`: Create an Apple Mail setup link
- `DELETE /api/v2/shared-hosting/{accountId}/email-accounts/{address}`: Delete an email account
- `PUT /api/v2/shared-hosting/{accountId}/email-accounts/{address}/quota`: Change an email account quota

### Headers

- `Authorization`: Bearer $HOSTUP_API_KEY
- Scopes: `console:services`, `write:hosting`

### Parameters

- `accountId` (path, string, required): The hosting account ID (`acct_…`). Example: `acct_01hxa3b4c5d6e7f8g9h0j1k2m3`
- `address` (path, string, required): The email address (`hello@example.com`) or the email account ID (`mail_…`). Unicode IDN and punycode spellings are both accepted. Example: `user@example.com`

### Request Example

```bash
curl -X POST "https://cloud.hostup.se/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/email-accounts/user@example.com/actions/sso" \
  -H "Authorization: Bearer $HOSTUP_API_KEY" \
  -H "Content-Type: application/json"
```

### Response Schema

- `loginUrl` (string, required): One-time login link to webmail, opening on the inbox. Example: `https://server.example.com:2096/cpsessXXXXXXXXXX/login?session=YOUR_TOKEN&goto_uri=%2F3rdparty%2Froundcube%2Findex.php`
- `expiresAt` (string, required, nullable): Always `null`. The server does not report when the link expires. Example: `null`
- `singleUse` (boolean, required): Always `true`. The link works once. Example: `true`

### Responses

#### 200 - The webmail login link.
```json
{
  "loginUrl": "https://server.example.com:2096/cpsessXXXXXXXXXX/login?session=YOUR_TOKEN&goto_uri=%2F3rdparty%2Froundcube%2Findex.php",
  "expiresAt": null,
  "singleUse": true
}
```

#### 400 - `{address}` is not a valid email address or a known email account ID.
```json
{
  "type": "https://developer.hostup.se/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "detail": "Invalid email address.",
  "code": "invalid_request",
  "instance": "/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/email-accounts/hello%40example.com/actions/sso",
  "errors": [
    {
      "pointer": "/path/address",
      "detail": "Invalid email address.",
      "code": "invalid_request"
    }
  ]
}
```

#### 401 - Unauthorized. Authentication is required.
```json
{
  "type": "https://developer.hostup.se/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication is required.",
  "code": "unauthorized",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 403 - The mailbox domain is not on this hosting account (`domain_not_owned`), the API key lacks a required scope or the account is not active.
```json
{
  "type": "https://developer.hostup.se/errors/domain_not_owned",
  "title": "Domain not owned by hosting account",
  "status": 403,
  "detail": "The requested domain is not hosted on this cPanel account.",
  "code": "domain_not_owned",
  "instance": "/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/email-accounts/hello%40example.com/actions/sso"
}
```

#### 404 - Not found. The resource does not exist or is not owned by the caller.
```json
{
  "type": "https://developer.hostup.se/errors/not_found",
  "title": "Not found",
  "status": 404,
  "detail": "The requested resource could not be found.",
  "code": "not_found",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 409 - The account is on Hostup's previous hosting platform. Webmail login links are only made for accounts on cPanel.
```json
{
  "type": "https://developer.hostup.se/errors/account_not_eligible_cpanel",
  "title": "Control panel action unavailable",
  "status": 409,
  "detail": "Webmail login is unavailable on the account's current platform. This account uses HostUp's previous hosting platform. Contact support and we will migrate the existing account to cPanel at no extra charge; no new hosting plan is needed.",
  "code": "account_not_eligible_cpanel",
  "instance": "/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/email-accounts/hello%40example.com/actions/sso"
}
```

#### 429 - Rate limited. Retry after the limit resets. 429 responses include `Retry-After` seconds plus `X-RateLimit-*` headers.
```json
{
  "type": "https://developer.hostup.se/errors/rate_limit_exceeded",
  "title": "Too many requests",
  "status": 429,
  "detail": "Rate limit exceeded. Please try again later.",
  "code": "rate_limit_exceeded",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 500 - Internal error. Retry later or contact support if the issue persists.
```json
{
  "type": "https://developer.hostup.se/errors/internal_error",
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected error occurred. Retry later or contact support if the issue persists.",
  "code": "internal_error",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 502 - Webmail could not be opened on the server. Try again.
```json
{
  "type": "https://developer.hostup.se/errors/upstream_failed",
  "title": "Upstream request failed",
  "status": 502,
  "detail": "We could not open webmail right now.",
  "code": "upstream_failed",
  "instance": "/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/email-accounts/hello%40example.com/actions/sso"
}
```
