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

**List incoming mail deliveries**

Shows what the hosting server did with incoming mail for the mailboxes of one domain over the last days: delivered, delayed (`deferred`, the sending server tries again) or `failed` (the sender got a bounce). A bounce goes only to the sender. This read shows it to the mailbox owner too. Failed and delayed messages are grouped in `problems` by the address the sender used, `+tag` included, with the server's reason. Only mail the server handled for this account's mailboxes is listed. The server keeps 10 days of tracking. `isComplete: false` means older rows in the window are missing. The domain must be on the account (main, addon, parked or subdomain).

### Related Endpoints

- `GET /api/v2/shared-hosting/{accountId}`: Get a web hosting account
- `PATCH /api/v2/shared-hosting/{accountId}`: Rename a web hosting account
- `GET /api/v2/shared-hosting/{accountId}/php`: Get PHP versions per website

### Headers

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

### Parameters

- `accountId` (path, string, required): The hosting account ID (`acct_…`). Example: `acct_01hxa3b4c5d6e7f8g9h0j1k2m3`
- `domain` (query, string, required): Domain on the hosting account. Unicode IDN and punycode spellings are both accepted. Example: `example.com`
- `address` (query, string): One mailbox on `domain`. A `+tag` is ignored. Mail to every `+tag` of the mailbox is included. Example: `info@example.com`
- `days` (query, integer) [min: 1, max: 10]: Days back to read, 1–10. Default 7. Example: `7`

### Request Example

```bash
curl "https://cloud.hostup.se/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/email-deliveries?domain=example.com" \
  -H "Authorization: Bearer $HOSTUP_API_KEY"
```

### Response Schema

- `domain` (string, required): The domain. IDNs are in Unicode form. Example: `example.com`
- `address` (string, required, nullable): The mailbox the read was narrowed to, without a `+tag`. `null` for the whole domain. Example: `null`
- `windowStartAt` (string, required): Start of the time window read. Example: `2026-10-15T10:00:00.000Z`
- `windowEndAt` (string, required): End of the time window read. Example: `2026-10-22T10:00:00.000Z`
- `deliveredCount` (integer, required): Messages delivered to a mailbox. Example: `187`
- `deferredCount` (integer, required): Delayed deliveries. The sending server tries again. Example: `0`
- `failedCount` (integer, required): Failed deliveries. Each sender got a bounce. Example: `10`
- `isComplete` (boolean, required): `false` when the server's row limit was reached and older rows in the window are missing. Example: `true`
- `problems` (array<object>, required): Failed and delayed messages grouped by status, problem and the address the sender used, most frequent first.
- `problems[].problem` (string, required): `invalid_address_characters`: the address has characters the mailbox server refuses, typically å, ä, ö or a space after a `+`. `mailbox_full`: the mailbox is over its quota. `unknown_recipient`: no mailbox or forwarder for the address. `temporary`: a delay without a more specific cause. `other`: see `reason`. Example: `invalid_address_characters`
  Allowed values: invalid_address_characters, mailbox_full, unknown_recipient, temporary, other
- `problems[].status` (string, required) Example: `failed`
  Allowed values: deferred, failed
- `problems[].addressedTo` (string, required): The address the sender used, `+tag` included. Quoted when it holds characters that need quotes. Example: `"info+Leverantörer"@example.com`
- `problems[].reason` (string, required): The server's reason, as recorded. Example: `LMTP error after RCPT TO:<"info+Leverantörer"@example.com>: 501 5.5.4 Invalid TO: Invalid character in quoted string`
- `problems[].messageCount` (integer, required): Messages in the group. Example: `10`
- `problems[].firstAttemptedAt` (string, required): The first attempt in the window. Example: `2026-10-15T08:03:15.000Z`
- `problems[].lastAttemptedAt` (string, required): The last attempt in the window. Example: `2026-10-22T08:00:47.000Z`
- `problems[].senderDomains` (array<string>, required): The most frequent sender domains, at most five. Example: `["supplier.example","newsletter.example"]`
- `recentDeliveries` (array<object>, required): The newest deliveries in the window, at most 50, newest first.
- `recentDeliveries[].attemptedAt` (string, required): When the server handled the message. Example: `2026-10-22T08:00:47.000Z`
- `recentDeliveries[].status` (string, required) Example: `failed`
  Allowed values: delivered, deferred, failed
- `recentDeliveries[].recipient` (string, required): The mailbox the message was for. Example: `info@example.com`
- `recentDeliveries[].addressedTo` (string, required): The address the sender used, `+tag` included. Example: `"info+Leverantörer"@example.com`
- `recentDeliveries[].senderAddress` (string, required, nullable): Envelope sender address. `null` when the message had none. Example: `orders@supplier.example`
- `recentDeliveries[].senderHost` (string, required, nullable): Host name of the sending server. Example: `mta3.supplier.example`
- `recentDeliveries[].reason` (string, required, nullable): The server's reason for a delayed or failed delivery. `null` when delivered. Example: `LMTP error after RCPT TO:<"info+Leverantörer"@example.com>: 501 5.5.4 Invalid TO: Invalid character in quoted string`

### Responses

#### 200 - Incoming mail for the domain, newest first.
```json
{
  "domain": "example.com",
  "address": null,
  "windowStartAt": "2026-10-15T10:00:00.000Z",
  "windowEndAt": "2026-10-22T10:00:00.000Z",
  "deliveredCount": 187,
  "deferredCount": 0,
  "failedCount": 10,
  "isComplete": true,
  "problems": [
    {
      "problem": "invalid_address_characters",
      "status": "failed",
      "addressedTo": "\"info+Leverantörer\"@example.com",
      "reason": "LMTP error after RCPT TO:<\"info+Leverantörer\"@example.com>: 501 5.5.4 Invalid TO: Invalid character in quoted string",
      "messageCount": 10,
      "firstAttemptedAt": "2026-10-15T08:03:15.000Z",
      "lastAttemptedAt": "2026-10-22T08:00:47.000Z",
      "senderDomains": [
        "supplier.example",
        "newsletter.example"
      ]
    }
  ],
  "recentDeliveries": [
    {
      "attemptedAt": "2026-10-22T08:00:47.000Z",
      "status": "failed",
      "recipient": "info@example.com",
      "addressedTo": "\"info+Leverantörer\"@example.com",
      "senderAddress": "orders@supplier.example",
      "senderHost": "mta3.supplier.example",
      "reason": "LMTP error after RCPT TO:<\"info+Leverantörer\"@example.com>: 501 5.5.4 Invalid TO: Invalid character in quoted string"
    }
  ]
}
```

#### 400 - `domain` is missing, `address` is not on `domain` or `days` is not 1–10.
```json
{
  "type": "https://developer.hostup.se/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "detail": "days must be an integer from 1 to 10.",
  "code": "invalid_request",
  "instance": "/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/email-deliveries",
  "errors": [
    {
      "pointer": "/query/days",
      "detail": "days must be an integer from 1 to 10.",
      "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 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-deliveries"
}
```

#### 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. Incoming mail cannot be read there through the API.
```json
{
  "type": "https://developer.hostup.se/errors/account_not_eligible_cpanel",
  "title": "Control panel action unavailable",
  "status": 409,
  "detail": "Incoming mail deliveries can only be read for hosting accounts on the cPanel control panel. 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-deliveries"
}
```

#### 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 - The server's delivery tracking could not be read right now. Try again.
```json
{
  "type": "https://developer.hostup.se/errors/upstream_failed",
  "title": "Upstream request failed",
  "status": 502,
  "detail": "Unable to read the incoming mail deliveries from the hosting server right now.",
  "code": "upstream_failed",
  "instance": "/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/email-deliveries"
}
```