## GET /api/v2/shared-hosting/{accountId}/email-accounts

**List email accounts**

List mailboxes on a cPanel-backed shared-hosting account. Get `accountId` from `GET /api/v2/shared-hosting` `data[].id`. If this returns `account_not_eligible_cpanel`, the selected hosting account uses HostUp's legacy control panel. Use the control panel SSO link to view mailboxes manually, or contact support to migrate the account to a newer cPanel-backed plan.

### Related Endpoints

- `POST /api/v2/shared-hosting/{accountId}/email-accounts`: Create email account
- `DELETE /api/v2/shared-hosting/{accountId}/email-accounts/{address}`: Delete mailbox
- `PUT /api/v2/shared-hosting/{accountId}/email-accounts/{address}/quota`: Replace mailbox quota

### Headers

- `Accept`: application/json
- `Authorization`: Bearer YOUR_API_KEY
- Required API scope: `read:hosting`

### Parameters

- `domain` (query, string): Optional domain filter. The domain must be hosted on the shared-hosting account. 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/email-accounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

### Response Schema

- `emailAccounts` (array<object>, required)
- `emailAccounts[].id` (string, required) Example: `mail_01hxa3b4c5d6e7f8g9h0j1k2m3`
- `emailAccounts[].email` (string, required) Example: `hello@example.com`
- `emailAccounts[].domain` (string, required) Example: `example.com`
- `emailAccounts[].quota` (object, required)
- `emailAccounts[].quota.usedGb` (number,null, required) Example: `0.125`
- `emailAccounts[].quota.limitGb` (number,null, required) Example: `32`
- `emailAccounts[].quota.usagePercent` (number,null, required) Example: `0.39`
- `emailAccounts[].quota.exceeded` (boolean, required) Example: `false`
- `quota` (object, required)
- `quota.used` (integer, required) Example: `1`
- `quota.limit` (integer,null, required) Example: `10`
- `quota.remaining` (integer,null, required) Example: `9`
- `actions` (object, required)
- `actions.canCreate` (object, required)
- `actions.canCreate.allowed` (boolean, required) Example: `true`
- `actions.canCreate.reason` (string,null, required) Example: `null`
- `actions.canCreate.code` (string,null, optional): Machine-readable reason code when an action is blocked. Example: `pending_order`

### Responses

#### 200 - Email account collection.
```json
{
  "emailAccounts": [
    {
      "id": "mail_01hxa3b4c5d6e7f8g9h0j1k2m3",
      "email": "hello@example.com",
      "domain": "example.com",
      "quota": {
        "usedGb": 0.125,
        "limitGb": 32,
        "usagePercent": 0.39,
        "exceeded": false
      }
    }
  ],
  "quota": {
    "used": 1,
    "limit": 10,
    "remaining": 9
  },
  "actions": {
    "canCreate": {
      "allowed": true,
      "reason": null
    }
  }
}
```

#### 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 - Forbidden. The caller lacks a required scope or does not own the resource.
```json
{
  "type": "https://developer.hostup.se/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "The caller lacks a required scope or does not own the resource.",
  "code": "forbidden",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 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 hosting account uses HostUp's legacy control panel, so mailbox listing is not available through this API.
```json
{
  "type": "https://developer.hostup.se/errors/account_not_eligible_cpanel",
  "title": "Control panel action unavailable",
  "status": 409,
  "detail": "Email account listing through the API is only supported 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.",
  "instance": "/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/email-accounts",
  "code": "account_not_eligible_cpanel"
}
```

#### 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"
}
```