Skip to content

Get domain email forwarding

GET /api/v2/domains/{id}/email-forwarding

Returns the email forwarding set up on the domain: whether it is on, the forwarding rules, the recipient addresses and the catch-all. This forwarding needs the domain’s DNS at Hostup. A domain on a web hosting account normally uses the forwarders on that account instead (/api/v2/shared-hosting/{accountId}/email-forwarders). integrationStatus is enabled (rules work), disabled (turn it on with PATCH) or unavailable (see reason). dnsActivation shows whether the DNS zone is ready. While it is activating, each read asks for the activation check again. It usually becomes active within minutes. The answer can come from a cached copy that is refreshed in the background. Send refresh=true to read the current state.

Authentication: An API key with the scopes read:dns and read:domains. About keys and scopes

Request

Path parameters

idstringrequired
The domain ID (dom_…).

Query parameters

refreshstring
Set to true to skip the cached copy and read the current state. Default false. One of true, false. Default "false".

Example

GET /api/v2/domains/{id}/email-forwarding
curl "https://cloud.hostup.se/api/v2/domains/dom_01hxa3b4c5d6e7f8g9h0j1k2m3/email-forwarding" \
-H "Authorization: Bearer $HOSTUP_API_KEY"

Responses

200 The domain’s email forwarding state.

Response 200
{
"enabled": false,
"integrationStatus": "disabled",
"reason": "Email forwarding is not enabled for this domain. Enable it to start receiving rules.",
"maxRules": 200,
"ruleCount": 0,
"rules": [],
"destinations": [],
"catchAll": null,
"existingMxRecords": [
{
"type": "MX",
"value": "mail.example.com",
"priority": 10
}
],
"dnsActivation": {
"status": "active",
"reason": null,
"checkedAt": "2026-08-22T12:00:00.000Z"
},
"actions": {
"canCreateNewRule": {
"allowed": false,
"reason": "Email forwarding is not enabled for this domain. Enable it to start receiving rules."
},
"canSetCatchAll": {
"allowed": false,
"reason": "Email forwarding is not enabled for this domain. Enable it to start receiving rules."
}
}
}
Response fields
enabledboolean
integrationStatusstring
One of enabled, disabled, unavailable.
reasonstring or null
maxRulesinteger
ruleCountinteger
rulesarray of object
idstring
emailstring
destinationstring
isEnabledboolean
namestring or null
priorityinteger
destinationsarray of object
idstring
emailstring
verificationStatusstring
One of verified, pending, unverified.
createdAtstring or null
verifiedAtstring or null
catchAllobject | null
actionstring
One of forward, drop, disabled.
destinationstring or null
existingMxRecordsarray of object
typestring
One of MX.
valuestring
priorityinteger or null
dnsActivationobject
Whether the domain’s DNS zone at Hostup is live. E-mail forwarding runs on it. active: forwarding can be turned on now. activating: the domain already uses our nameservers and the zone is being activated. Reading this resource starts the check. Poll until active, usually a few minutes. not_delegated: the domain uses other nameservers. unavailable: there is no zone at Hostup or its state could not be read.
statusstring
One of active, activating, not_delegated, unavailable.
reasonstring or null
Why the zone is not active, in plain words. Null when it is active.
checkedAtstring
actionsobject
canCreateNewRuleobject
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.
canSetCatchAllobject
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.

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 names the missing resource: domain_not_found, email_forwarding_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.