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
idstringrequireddom_…).Body
enabledbooleanrequiredtrue turns forwarding on. false turns it off.forcebooleanenabled: true. Default false.Example
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 }'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, "force": true }'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": false }'Responses
200 The email forwarding state after the change.
{ "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
enabledbooleanintegrationStatusstringenabled, disabled, unavailable.reasonstring or nullmaxRulesintegerruleCountintegerrulesarray of objectidstringemailstringdestinationstringisEnabledbooleannamestring or nullpriorityintegerdestinationsarray of objectidstringemailstringverificationStatusstringverified, pending, unverified.createdAtstring or nullverifiedAtstring or nullcatchAllobject | nullactionstringforward, drop, disabled.destinationstring or nullexistingMxRecordsarray of objecttypestringMX.valuestringpriorityinteger or nulldnsActivationobjectactive: 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.statusstringactive, activating, not_delegated, unavailable.reasonstring or nullcheckedAtstringactionsobjectcanCreateNewRuleobjectallowedbooleanreasonstring or nullcodestring or nullcanSetCatchAllobjectallowedbooleanreasonstring or nullcodestring or nullErrors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | The body is not valid. enabled is required. force is only allowed with enabled: true. No other field is allowed. |
| 401 | Unauthorized. Authentication is required. |
| 403 | Forbidden. The caller lacks a required scope or does not own the resource. |
| 404 | The domain was not found (domain_not_found). When turning forwarding off, the domain can also have no forwarding set up (email_forwarding_not_found). |
| 409 | The 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). |
| 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. |
| 502 | The 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). |
| 503 | force was sent but the DNS zone status could not be read (upstream_unavailable). Nothing was changed. |