Skip to content
HostupDevelopers
GuidesAPI referenceSupport

Count outbound mail relay messages by status

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

Counts the messages one sender passed through the outbound mail relay, per status. The count starts at since, by default 7 days ago. The statuses mean the same as status on GET /api/v2/me/mail-relay/messages. Use that endpoint to see the messages themselves. Choose the sender with scope as on the message log. A VPS with no public IP address returns zero counts.

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

Request

Query parameters

scopestringrequired
Which sender to count. 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.
sincestring
Count messages the relay received at or after this time (ISO 8601). Default 7 days ago. A time more than 30 days back counts from 30 days ago.

Example

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

Responses

200 The counts per status.

Response 200
{
  "windowStartAt": "2026-10-02T10:00:00.000Z",
  "counts": {
    "delivered": 412,
    "sending": 2,
    "queued": 0,
    "deferred": 3,
    "bounced": 5,
    "rejected": 1,
    "total": 423
  }
}
Response fields
windowStartAtstring
Start of the counted period.
countsobject
Messages per status since windowStartAt.
deliveredinteger
The receiving server accepted the message. At least 0.
sendinginteger
On its way out, no answer from the receiving server yet. At least 0.
queuedinteger
Waiting at the relay, also while the sender is paused. At least 0.
deferredinteger
The receiving server asked to try again later. At least 0.
bouncedinteger
The receiving server refused the message or delivery was given up. At least 0.
rejectedinteger
The relay refused the message. At least 0.
totalinteger
All messages counted. At least 0.

Errors

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

400Invalid request. The response body is an RFC 7807 Problem Details document.
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 counts did not load within 5 seconds. Try again after the Retry-After seconds (30).

This page as MarkdownOpenAPI spec