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
idstringrequiredvps_…).Example
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.
{ "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 nulltokenstring or nulldnsRecord. A VPS with several IPv4 addresses gets one value per address, separated by commas. Null without a sending IP.dnsRecordstring or nullyourdomain.com with the domain. Null without a sending IP.quotaobject or nullinsightsStatusstringavailable 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 nullBLOCKED when a sender of the VPS is paused, ACTIVE otherwise. Null when no data could be loaded.alertTotalintegerwindowDays days.alertBucketsarray of objectwindowDays days.datestringYYYY-MM-DD.countintegeralertsarray of objectconditionNamestringEMAIL_BLOCK, DOMAIN_BLOCK, ENVELOPE_BLOCK or IP_BLOCK.descriptionstring or nullenvelopeSenderstring or nullreasonobjectcodestringCSR 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.titlestringdescriptionstringactionsarray of stringtimestampstringrecentBlocksarray of objectwindowDays days, newest first.timestampstringsenderstring or nullrecipientDomainstring or nullresponseCodestring or null450 (try later) or 550 (rejected). Null for other events.responseMessagestring or nulllastCommandstring or nullMAIL FROM, RCPT TO or DATA.reasonobjectcodestringCSR 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.titlestringdescriptionstringactionsarray of stringspamDispositionstringCONFIRMED when the message was judged as spam. Otherwise UNKNOWN.virusDispositionstringUNKNOWN.remediationOptionstring or nullsenderDomainstring or nulleventTypestringspam_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 nullemail, domain, envelope or ip. One of email, domain, envelope, ip.categorystring or nullspam or phishing.categoryLabelstring or nullcategory as a label to show.confidencenumber or nullblockedUntilstring or nulldeliverySummaryobjectwindowDays days.deliverednumber or nullblockednumber or nullrejectednumber or nulldeferrednumber or nullwindowDaysintegerrefreshedAtstring or nullactiveBlocksarray of objectblockedUntil.scopestringemail (one sender address), domain, envelope or ip. One of email, domain, envelope, ip.valuestring*@ and its domain.senderDomainstring or nullreasonobjectcodestringCSR 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.titlestringdescriptionstringactionsarray of stringsummarystring or nullcategorystring or nullspam or phishing.categoryLabelstring or nullcategory as a label to show.confidencenumber or nullblockedUntilstringupdatedAtstringmanualUnblockAvailablebooleanPOST /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.
| 400 | Invalid request. The response body is an RFC 7807 Problem Details document. |
| 401 | Unauthorized. Authentication is required. |
| 403 | Forbidden. The caller lacks a required scope or does not own the resource. |
| 404 | Not found. The resource does not exist or is not owned by the caller; code is vps_not_found. |
| 429 | Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers. |
| 500 | Internal error. Retry later or contact support if the issue persists. |