Skip to content

Get the mail relay status of a VPS

GET /api/v2/vps/{id}/mail-relay

Shows how the VPS sends mail through Hostup’s outgoing mail relay. It returns the DNS record your sending domains need, the monthly sending limit of the account and what the relay blocked in the last 7 days. Add dnsRecord as a TXT record named _hostup on each domain the VPS sends mail for. The limit in quota covers all VPSs on the account together. Raise it with POST /api/v2/vps/{id}/mail-relay/quota-requests (prepaid) or POST /api/v2/vps/{id}/mail-relay/charge-consent (pay-as-you-go). Paused senders are listed in activeBlocks. Lift a pause with POST /api/v2/me/mail-relay/blocks/unblock.

Authentication: An API key with the scope read:vm. About keys and scopes

Request

Path parameters

idstringrequired
The VPS ID (vps_…).

Example

GET /api/v2/vps/{id}/mail-relay
curl "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/mail-relay" \
-H "Authorization: Bearer $HOSTUP_API_KEY"

Responses

200 Mail relay status of the VPS.

Response 200
{
"ip": "203.0.113.10",
"token": "h_MjAzLjAuMTEzLjEw_3f9a2c71b8d0",
"dnsRecord": "_hostup.yourdomain.com TXT \"v=mc1 auth=h_MjAzLjAuMTEzLjEw_3f9a2c71b8d0\"",
"quota": {
"ipAddress": "203.0.113.10",
"period": "2026-11",
"scope": "client",
"quotaSource": "custom",
"status": "active",
"includedMonthlyLimit": 15000,
"extraMonthlyQuota": 0,
"monthlyLimit": 15000,
"usedThisMonth": 3200,
"additionalBillableEmails": 0,
"rejectedThisMonth": 4,
"deferredThisMonth": 0,
"remainingThisMonth": 11800,
"usagePercent": 21.3,
"notifyNearPercent": 80,
"nearLimit": false,
"limitReached": false,
"paygEnabled": false,
"prepaidEnabled": false,
"prepaidMonthlyLimit": 0,
"prepaidExtraQuota": 0,
"paygEligible": true,
"paygConsentEnabled": false,
"paygConsentRequired": true,
"paygStatus": "active",
"paygCheckedAt": "2026-11-02T08:00:00.000Z",
"paygRequired": false,
"cacheTtlSeconds": 10,
"billingMode": "included_only",
"pendingRequest": null,
"pricing": {
"amount": 5,
"currencyCode": "SEK",
"unitEmails": 1000
}
},
"insightsStatus": "available",
"policyDisposition": "ACTIVE",
"alertTotal": 0,
"alertBuckets": [
{
"date": "2026-11-02",
"count": 0
}
],
"alerts": [],
"recentBlocks": [],
"deliverySummary": {
"delivered": null,
"blocked": null,
"rejected": null,
"deferred": null
},
"windowDays": 7,
"refreshedAt": "2026-11-02T12:00:00.000Z",
"activeBlocks": []
}
Response fields
ipstring or null
The IP address the VPS sends mail from. Null when the VPS has none yet.
tokenstring or null
The authorisation value inside dnsRecord. A VPS with several IPv4 addresses gets one value per address, separated by commas. Null without a sending IP.
dnsRecordstring or null
The TXT record to add on each sending domain. Replace yourdomain.com with the domain. Null without a sending IP.
quotaobject or null
The monthly sending limit of the account. It covers all VPSs on the account. Null when the VPS has no sending IP yet.
insightsStatusstring
Whether block and delivery data could be loaded. available when it could. missing_ip when the VPS has no sending IP. Other values mean the data is missing for now. One of available, missing_ip, not_configured, rate_limited, unavailable.
policyDispositionstring or null
BLOCKED when a sender of the VPS is paused, ACTIVE otherwise. Null when no data could be loaded.
alertTotalinteger
Messages the relay blocked, rejected or deferred in the last windowDays days.
alertBucketsarray of object
Blocked, rejected or deferred messages per day for the last windowDays days.
datestring
The day, as YYYY-MM-DD.
countinteger
Blocked, rejected or deferred messages on that day.
alertsarray of object
Up to 5 current blocks as alerts.
conditionNamestring
What is blocked: EMAIL_BLOCK, DOMAIN_BLOCK, ENVELOPE_BLOCK or IP_BLOCK.
descriptionstring or null
Short summary of the block.
envelopeSenderstring or null
The sender domain.
reasonobject
Why the relay acted, with steps to fix it.
codestring
Reason code. CSR spam-like volume, ESA repeated abuse, CS one message looked like spam, INVALID_FROM_HEADER missing or bad From header, BFD SPF policy failed, TCR too many receiver errors, UNKNOWN other. One of CSR, ESA, CS, INVALID_FROM_HEADER, BFD, TCR, UNKNOWN.
titlestring
Short title of the reason.
descriptionstring
The reason in a sentence or two.
actionsarray of string
Steps the sender can take.
timestampstring
When the block was last updated.
recentBlocksarray of object
Up to 10 messages the relay blocked, rejected or deferred in the last windowDays days, newest first.
timestampstring
When it happened.
senderstring or null
The sender domain.
recipientDomainstring or null
The recipient’s domain.
responseCodestring or null
SMTP reply code the relay gave, 450 (try later) or 550 (rejected). Null for other events.
responseMessagestring or null
Short summary of what happened.
lastCommandstring or null
The SMTP step where it happened: MAIL FROM, RCPT TO or DATA.
reasonobject
Why the relay acted, with steps to fix it.
codestring
Reason code. CSR spam-like volume, ESA repeated abuse, CS one message looked like spam, INVALID_FROM_HEADER missing or bad From header, BFD SPF policy failed, TCR too many receiver errors, UNKNOWN other. One of CSR, ESA, CS, INVALID_FROM_HEADER, BFD, TCR, UNKNOWN.
titlestring
Short title of the reason.
descriptionstring
The reason in a sentence or two.
actionsarray of string
Steps the sender can take.
spamDispositionstring
CONFIRMED when the message was judged as spam. Otherwise UNKNOWN.
virusDispositionstring
Always UNKNOWN.
remediationOptionstring or null
Always null.
senderDomainstring or null
The sender domain.
eventTypestring
What the relay did. spam_drop dropped as spam, domain_block sender domain blocked, already_blocked sender already paused, policy_defer deferred, policy_reject rejected by policy, quota_reject monthly limit reached, message_rejected message rejected. One of clean_release, spam_drop, domain_block, already_blocked, policy_defer, policy_reject, quota_reject, message_rejected.
scopestring or null
What the block applies to: email, domain, envelope or ip. One of email, domain, envelope, ip.
categorystring or null
Category of the mail, for example spam or phishing.
categoryLabelstring or null
category as a label to show.
confidencenumber or null
How sure the relay was, from 0 to 1. 0 to 1.
blockedUntilstring or null
When the block ends. Null when nothing was blocked.
deliverySummaryobject
Counts of relay events in the last windowDays days.
deliverednumber or null
Messages delivered.
blockednumber or null
Messages blocked.
rejectednumber or null
Messages rejected.
deferrednumber or null
Messages deferred.
windowDaysinteger
Number of days the alerts, blocks and counts cover.
refreshedAtstring or null
When this data was read.
activeBlocksarray of object
Senders of the VPS that are paused right now, up to 10. A pause ends at blockedUntil.
scopestring
What is paused: email (one sender address), domain, envelope or ip. One of email, domain, envelope, ip.
valuestring
The paused sender. An address is shown as *@ and its domain.
senderDomainstring or null
The sender domain.
reasonobject
Why the relay acted, with steps to fix it.
codestring
Reason code. CSR spam-like volume, ESA repeated abuse, CS one message looked like spam, INVALID_FROM_HEADER missing or bad From header, BFD SPF policy failed, TCR too many receiver errors, UNKNOWN other. One of CSR, ESA, CS, INVALID_FROM_HEADER, BFD, TCR, UNKNOWN.
titlestring
Short title of the reason.
descriptionstring
The reason in a sentence or two.
actionsarray of string
Steps the sender can take.
summarystring or null
Short summary of the pause.
categorystring or null
Category of the mail, for example spam or phishing.
categoryLabelstring or null
category as a label to show.
confidencenumber or null
How sure the relay was, from 0 to 1. 0 to 1.
blockedUntilstring
When the pause ends.
updatedAtstring
When the pause was last updated.
manualUnblockAvailableboolean
Always false. Use POST /api/v2/me/mail-relay/blocks/unblock to lift a pause.

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.
404Not found. The resource does not exist or is not owned by the caller; code is vps_not_found.
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.