Skip to content
HostupDevelopers
GuidesAPI referenceSupport

List outbound mail relay messages

GET /api/v2/me/mail-relay/messages

Lists the messages one sender passed through the outbound mail relay in the last 30 days, with how each delivery went. Choose the sender with scope. Use hosting with domain for a domain on your web hosting. Use vps with vpsId for a VPS that sends through relay.hostup.se. For a VPS, mail from all its public IP addresses is listed. Each row has the sender, recipients, subject, status and a timeline of the delivery. For counts per status, use GET /api/v2/me/mail-relay/summary.

Authentication: An API key with one of these scopes: read:hosting, read:vm. About keys and scopes

Request

Query parameters

scopestringrequired
Which sender to list. hosting takes domain and needs the scope read:hosting. vps takes vpsId and needs read:vm. One of hosting, vps.
domainstring
A domain on one of your web hosting accounts (main, addon, parked or subdomain). Required when scope is hosting.
vpsIdstring
The VPS ID (vps_…). Required when scope is vps.
statusstring
Only messages in this status. The values are explained under status in the response. One of queued, sending, delivered, deferred, bounced, rejected.
sincestring
Only messages the relay received at or after this time (ISO 8601). Default and earliest: 30 days ago.
limitinteger
Messages per page, 1 to 100. Default 20. A higher value returns 100. A value below 1 returns 400 invalid_request. Default 20. 1 to 100.
cursorstring
The nextCursor from the previous page.

Example

GET /api/v2/me/mail-relay/messages
curl "https://cloud.hostup.se/api/v2/me/mail-relay/messages?scope=hosting" \
  -H "Authorization: Bearer $HOSTUP_API_KEY"

Responses

200 One page of messages, newest first.

Response 200
{
  "data": [
    {
      "id": "3f0c1d2e-9b7a-4c55-8e21-0c4a5b6d7e8f",
      "receivedAt": "2026-10-08T09:58:12.000Z",
      "from": "[email protected]",
      "to": [
        "[email protected]"
      ],
      "subject": "Faktura 1234",
      "status": "delivered",
      "lastReply": null,
      "deliveredAt": "2026-10-08T09:58:20.000Z",
      "rejectedReason": null,
      "verdictCategory": "clean",
      "reviewState": null,
      "guard": null,
      "events": [
        {
          "at": "2026-10-08T09:58:12.000Z",
          "kind": "accepted",
          "detail": null
        },
        {
          "at": "2026-10-08T09:58:20.000Z",
          "kind": "sent",
          "detail": "250 2.0.0 OK"
        }
      ]
    },
    {
      "id": "8a1b2c3d-4e5f-4a6b-9c7d-0e1f2a3b4c5d",
      "receivedAt": "2026-10-07T14:21:03.000Z",
      "from": "[email protected]",
      "to": [
        "[email protected]"
      ],
      "subject": "Orderbekräftelse",
      "status": "bounced",
      "lastReply": "550 5.1.1 The email account that you tried to reach does not exist",
      "deliveredAt": null,
      "rejectedReason": null,
      "verdictCategory": "clean",
      "reviewState": null,
      "guard": null,
      "events": [
        {
          "at": "2026-10-07T14:21:03.000Z",
          "kind": "accepted",
          "detail": null
        },
        {
          "at": "2026-10-07T14:21:09.000Z",
          "kind": "bounced",
          "detail": "550 5.1.1 The email account that you tried to reach does not exist"
        }
      ]
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
Response fields
dataarray of object
idstring
Message ID in the relay’s log.
receivedAtstring
When the relay accepted the message from your server.
fromstring or null
The sender address.
toarray of string
The recipient addresses.
subjectstring or null
The subject line.
statusstring
queued: waiting at the relay, also while the sender is paused. sending: on its way out. delivered: the receiving server accepted it. deferred: the receiving server asked to try again later. bounced: the receiving server refused it or delivery was given up. rejected: the relay refused it. One of queued, sending, delivered, deferred, bounced, rejected.
lastReplystring or null
The receiving server’s last reply, for example on a deferred or bounced message.
deliveredAtstring or null
When the receiving server accepted the message.
rejectedReasonstring or null
Why the relay refused the message. Only set when status is rejected.
verdictCategorystring or null
The content classification, for example clean, spam, phishing, scam or malware.
reviewStatestring or null
On a rejected message, the result of the second review: confirmed (the rejection stands), overturned (it was reversed) or pending (not reviewed yet). Null on other statuses. One of confirmed, overturned, pending.
guardstring or null
Name of the relay rule that decided how a flagged message was handled. Informational only.
eventsarray of object
What happened to the message, step by step.
atstring
When the step happened.
kindstring
What happened, for example accepted, queued, sent, deferred, bounced or rejected.
detailstring or null
The receiving server’s reply or the relay’s note for this step.
hasMoreboolean
True when there is another page.
nextCursorstring or null
Send as cursor to get the next page. Null on the last page.

Errors

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

400invalid_request: the query is wrong. For example scope is missing or unknown, domain or vpsId is missing for the chosen scope, limit is below 1 or not a number, cursor is longer than 512 characters, or status or since is not a valid value. Each entry in errors names the parameter.
401Unauthorized. Authentication is required.
403Forbidden. The caller lacks a required scope or does not own the resource.
404domain_not_found: the domain is not on any of your web hosting accounts. vps_not_found: the VPS is not on your account.
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.
503upstream_unavailable: the message log did not answer within 5 seconds. Try again after the Retry-After seconds (30).

This page as MarkdownOpenAPI spec