Skip to content
HostupDevelopers
GuidesAPI referenceSupport

List incoming mail deliveries

GET /api/v2/shared-hosting/{accountId}/email-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).

Authentication: An API key with the scopes read:hosting and console:services. About keys and scopes

Request

Path parameters

accountIdstringrequired
The hosting account ID (acct_…).

Query parameters

domainstringrequired
Domain on the hosting account. Unicode IDN and punycode spellings are both accepted.
addressstring
One mailbox on domain. A +tag is ignored. Mail to every +tag of the mailbox is included.
daysinteger
Days back to read, 1–10. Default 7. Default 7. 1 to 10.

Example

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

Responses

200 Incoming mail for the domain, newest first.

Response 200
{
  "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": "[email protected]",
      "addressedTo": "\"info+Leverantörer\"@example.com",
      "senderAddress": "[email protected]",
      "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"
    }
  ]
}
Response fields
domainstring
The domain. IDNs are in Unicode form.
addressstring or null
The mailbox the read was narrowed to, without a +tag. null for the whole domain.
windowStartAtstring
Start of the time window read.
windowEndAtstring
End of the time window read.
deliveredCountinteger
Messages delivered to a mailbox. At least 0.
deferredCountinteger
Delayed deliveries. The sending server tries again. At least 0.
failedCountinteger
Failed deliveries. Each sender got a bounce. At least 0.
isCompleteboolean
false when the server’s row limit was reached and older rows in the window are missing.
problemsarray of object
Failed and delayed messages grouped by status, problem and the address the sender used, most frequent first.
problemstring
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. One of invalid_address_characters, mailbox_full, unknown_recipient, temporary, other.
statusstring
One of deferred, failed.
addressedTostring
The address the sender used, +tag included. Quoted when it holds characters that need quotes.
reasonstring
The server’s reason, as recorded.
messageCountinteger
Messages in the group. At least 1.
firstAttemptedAtstring
The first attempt in the window.
lastAttemptedAtstring
The last attempt in the window.
senderDomainsarray of string
The most frequent sender domains, at most five.
recentDeliveriesarray of object
The newest deliveries in the window, at most 50, newest first.
attemptedAtstring
When the server handled the message.
statusstring
One of delivered, deferred, failed.
recipientstring
The mailbox the message was for.
addressedTostring
The address the sender used, +tag included.
senderAddressstring or null
Envelope sender address. null when the message had none.
senderHoststring or null
Host name of the sending server.
reasonstring or null
The server’s reason for a delayed or failed delivery. null when delivered.

Errors

Errors are Problem Details with a stable code. Branch on the code, not on the text.

400domain is missing, address is not on domain or days is not 1–10.
401Unauthorized. Authentication is required.
403The domain is not on this hosting account (domain_not_owned), the API key lacks a required scope or the account is not active.
404Not found. The resource does not exist or is not owned by the caller.
409The account is on Hostup’s previous hosting platform. Incoming mail cannot be read there through the API.
429Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
500Internal error. Retry later or contact support if the issue persists.
502The server’s delivery tracking could not be read right now. Try again.

This page as MarkdownOpenAPI spec