## GET /api/v2/shared-hosting/{accountId}/mail-settings

**Get mail app settings for a hosted domain**

Return the IMAP/POP3/SMTP client settings and webmail address for one domain hosted on the account. The domain must be hosted on the account (main, addon, parked or sub domain), otherwise the request fails with 403 `domain_not_owned`. Accounts on a legacy control panel return 409 `account_not_eligible_cpanel`. The username for all servers and webmail is always the full email address; the password is the mailbox password. `alternativeHostname` (`mail.<domain>`) can replace the server hostname when the domain's SSL certificate covers it — the server hostname always has a valid certificate and is the safe default.

### Related Endpoints

- `GET /api/v2/shared-hosting/{accountId}`: Get shared-hosting account
- `PATCH /api/v2/shared-hosting/{accountId}`: Rename shared-hosting account
- `GET /api/v2/shared-hosting/{accountId}/backups`: List hosting backups

### Headers

- `Accept`: application/json
- `Authorization`: Bearer YOUR_API_KEY
- Required API scopes: `read:hosting`, `console:services`

### Parameters

- `domain` (query, string, required): Hosted domain to return mail app settings for. Example: `example.com`
- `accountId` (path, string, required): Public shared-hosting account ID. Get it from GET /api/v2/shared-hosting `data[].id`. Do not invent this value; use the exact ID returned by the referenced API response. Example: `acct_01hxa3b4c5d6e7f8g9h0j1k2m3`

### Request Example

```bash
curl -X GET "https://cloud.hostup.se/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/mail-settings?domain=example.com" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

### Response Schema

- `domain` (string, required) Example: `example.com`
- `incoming` (object, required)
- `incoming.imap` (object, required)
- `incoming.imap.hostname` (string, required) Example: `web12.hostup.se`
- `incoming.imap.port` (integer, required) Example: `993`
- `incoming.imap.encryption` (string, required) Example: `ssl_tls`
  Allowed values: ssl_tls, starttls
- `incoming.pop3` (object, required)
- `incoming.pop3.hostname` (string, required) Example: `web12.hostup.se`
- `incoming.pop3.port` (integer, required) Example: `995`
- `incoming.pop3.encryption` (string, required) Example: `ssl_tls`
  Allowed values: ssl_tls, starttls
- `outgoing` (object, required)
- `outgoing.smtp` (array<object>, required): Both supported submission endpoints; either works — port 465 uses implicit SSL/TLS (`ssl_tls`), port 587 uses STARTTLS (`starttls`).
- `outgoing.smtp[].hostname` (string, required) Example: `web12.hostup.se`
- `outgoing.smtp[].port` (integer, required) Example: `465`
- `outgoing.smtp[].encryption` (string, required) Example: `ssl_tls`
  Allowed values: ssl_tls, starttls
- `usernameFormat` (string, required): The mail app username is always the full email address (never a bare local part). Example: `full_email_address`
  Allowed values: full_email_address
- `webmailUrl` (string, required): Browser webmail login for the same mailboxes (sign in with the full email address and the mailbox password). Example: `https://web12.hostup.se:2096`
- `alternativeHostname` (string, required): mail.<domain> — usable instead of the server hostname when the domain's SSL certificate covers it; on certificate warnings, use the server hostname. Example: `mail.example.com`
- `notes` (array<string>, required): Plain-English setup guidance to show the customer verbatim.

### Responses

#### 200 - Mail app settings for the domain.
```json
{
  "domain": "example.com",
  "incoming": {
    "imap": {
      "hostname": "web12.hostup.se",
      "port": 993,
      "encryption": "ssl_tls"
    },
    "pop3": {
      "hostname": "web12.hostup.se",
      "port": 995,
      "encryption": "ssl_tls"
    }
  },
  "outgoing": {
    "smtp": [
      {
        "hostname": "web12.hostup.se",
        "port": 465,
        "encryption": "ssl_tls"
      },
      {
        "hostname": "web12.hostup.se",
        "port": 587,
        "encryption": "starttls"
      }
    ]
  },
  "usernameFormat": "full_email_address",
  "webmailUrl": "https://web12.hostup.se:2096",
  "alternativeHostname": "mail.example.com",
  "notes": [
    "Sign in with the full email address as the username and the mailbox password as the password — the same login works for webmail.",
    "mail.example.com can be used instead of web12.hostup.se for the incoming and outgoing servers, but its certificate depends on the domain's SSL setup. If the mail app shows a certificate or security warning, use web12.hostup.se — it always has a valid certificate.",
    "Use IMAP rather than POP3 when the mailbox is read on more than one device — IMAP keeps mail on the server and in sync."
  ]
}
```

#### 400 - Invalid request. The response body is an RFC 7807 Problem Details document.
```json
{
  "type": "https://developer.hostup.se/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "detail": "The request body failed validation.",
  "code": "invalid_request",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z",
  "errors": [
    {
      "pointer": "/items/0/domainName",
      "detail": "`domainName` is required.",
      "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 requested domain is not hosted on this account.
```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/mail-settings"
}
```

#### 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 a legacy control panel — mail app settings cannot be derived through the API.
```json
{
  "type": "https://developer.hostup.se/errors/account_not_eligible_cpanel",
  "title": "Control panel action unavailable",
  "status": 409,
  "detail": "Mail app settings can only be provided for hosting accounts on the cPanel control panel. This account uses HostUp's legacy control panel. Use the control panel SSO link to make the change manually, or contact support to migrate the account to a newer cPanel-backed plan.",
  "code": "account_not_eligible_cpanel",
  "instance": "/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/mail-settings"
}
```

#### 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": "Too many requests. Retry after the limit resets.",
  "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"
}
```