Skip to content

Turn domain email forwarding on or off

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

Turns email forwarding on or off for the domain and returns the new state. A domain on a web hosting account normally uses the forwarders on that account instead (/api/v2/shared-hosting/{accountId}/email-forwarders). Turning it on needs the domain’s DNS at Hostup with an active DNS zone (dnsActivation.status on GET /api/v2/domains/{id}/email-forwarding). If the domain has MX records that point elsewhere, the call returns 409 mx_records_conflict. existingMxRecords on GET /api/v2/domains/{id}/email-forwarding lists them. Send force: true to replace them. Mail for any mailbox that used those records then stops arriving there. Before the records are removed, the whole DNS zone is saved as a DNS snapshot (GET /api/v2/domains/{id}/dns/snapshots). If turning it on then fails, the call puts the old MX records back when it safely can. The 502 response says what happened in mxRecovery.status.

Authentication: An API key with the scopes write:email and write:domains. About keys and scopes

Request

Path parameters

idstringrequired
The domain ID (dom_…).

Body

enabledbooleanrequired
true turns forwarding on. false turns it off.
forceboolean
Replace the domain’s existing MX records while turning forwarding on. Only valid with enabled: true. Default false.

Example

PATCH /api/v2/domains/{id}/email-forwarding
curl -X PATCH "https://cloud.hostup.se/api/v2/domains/dom_01hxa3b4c5d6e7f8g9h0j1k2m3/email-forwarding" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": true
}'

Responses

200 The email forwarding state after the change.

Response 200
{
"enabled": true,
"integrationStatus": "enabled",
"reason": null,
"maxRules": 200,
"ruleCount": 0,
"rules": [],
"destinations": [],
"catchAll": {
"action": "disabled",
"destination": null
},
"existingMxRecords": [],
"dnsActivation": {
"status": "active",
"reason": null,
"checkedAt": "2026-08-22T12:00:00.000Z"
},
"actions": {
"canCreateNewRule": {
"allowed": true,
"reason": null
},
"canSetCatchAll": {
"allowed": true,
"reason": null
}
}
}
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.

400The body is not valid. enabled is required. force is only allowed with enabled: true. No other field is allowed.
401Unauthorized. Authentication is required.
403Forbidden. The caller lacks a required scope or does not own the resource.
404The domain was not found (domain_not_found). When turning forwarding off, the domain can also have no forwarding set up (email_forwarding_not_found).
409The DNS zone is still activating (dns_zone_activating, retry after recovery.retryAfterSeconds), the domain’s DNS is not at Hostup (domain_not_eligible) or MX records that point elsewhere are in the way (mx_records_conflict).
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.
502The forwarding service failed (external_provider_failed). When force has removed MX records and turning forwarding on then fails, the code is email_forwarding_enable_failed. Its mxRecovery.status is restored (the old records are back, retry later), changed (the records changed meanwhile and were left alone) or unconfirmed (contact support).
503force was sent but the DNS zone status could not be read (upstream_unavailable). Nothing was changed.