Skip to content

Create an email forwarding rule

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

Creates a forwarding rule that sends mail for one address on the domain to up to 10 recipients. Use it for a domain whose DNS is at Hostup. A domain on a web hosting account normally uses POST /api/v2/shared-hosting/{accountId}/email-forwarders instead. If forwarding is off, the call tries to turn it on first. Each recipient that is not verified yet gets a verification e-mail. The call then returns 200 with createOutcome.status: "verification_required". Once every recipient has clicked the link, the next fresh read of the forwarding state creates the rule (GET /api/v2/domains/{id}/email-forwarding?refresh=true). When every recipient is already verified, the rule is created at once and the call returns 201. A domain can have at most 200 rules.

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

sourcestringrequired
The address to forward, on this domain. Use PUT for a catch-all instead of *@.
destinationsarray of stringrequired
Where to forward the mail: 1 to 10 different addresses. An address cannot forward to itself.

Example

POST /api/v2/domains/{id}/email-forwarding
curl -X POST "https://cloud.hostup.se/api/v2/domains/dom_01hxa3b4c5d6e7f8g9h0j1k2m3/email-forwarding" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"source": "hello@example.com",
"destinations": [
"owner@example.net"
]
}'

Responses

200 No rule yet. One or more recipients must verify their address first. createOutcome.status is verification_required. createOutcome.verificationEmailsSent lists where a verification e-mail went.

Response 200
{
"enabled": true,
"integrationStatus": "enabled",
"reason": null,
"maxRules": 200,
"ruleCount": 0,
"rules": [],
"destinations": [
{
"id": "efd_01hxa3b4c5d6e7f8g9h0j1k2m3",
"email": "owner@example.net",
"verificationStatus": "pending",
"createdAt": "2026-04-27T12:00:00.000Z",
"verifiedAt": null
}
],
"catchAll": {
"action": "disabled",
"destination": null
},
"existingMxRecords": [],
"dnsActivation": {
"status": "active",
"reason": null,
"checkedAt": "2026-04-27T12:00:00.000Z"
},
"actions": {
"canCreateNewRule": {
"allowed": true,
"reason": null
},
"canSetCatchAll": {
"allowed": true,
"reason": null
}
},
"createOutcome": {
"status": "verification_required",
"reason": "Verify the destination address before creating the forwarding rule.",
"createdRuleCount": 0,
"createdRules": [],
"destinationsNeedingVerification": [
"owner@example.net"
],
"verificationEmailsSent": [
"owner@example.net"
]
}
}
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.
createOutcomeobject
createdRuleCountinteger
createdRulesarray of object
idstring
emailstring
destinationstring
isEnabledboolean
namestring or null
priorityinteger

201 The rule was created. The body is the new forwarding state with createOutcome.

Response 201
{
"enabled": true,
"integrationStatus": "enabled",
"reason": null,
"maxRules": 200,
"ruleCount": 1,
"rules": [
{
"id": "ef_01hxa3b4c5d6e7f8g9h0j1k2m3",
"email": "hello@example.com",
"destination": "owner@example.net",
"isEnabled": true,
"name": "hello",
"priority": 0
}
],
"destinations": [
{
"id": "efd_01hxa3b4c5d6e7f8g9h0j1k2m3",
"email": "owner@example.net",
"verificationStatus": "verified",
"createdAt": "2026-04-27T12:00:00.000Z",
"verifiedAt": "2026-04-27T12:05:00.000Z"
}
],
"catchAll": {
"action": "disabled",
"destination": null
},
"existingMxRecords": [],
"dnsActivation": {
"status": "active",
"reason": null,
"checkedAt": "2026-04-27T12:05:00.000Z"
},
"actions": {
"canCreateNewRule": {
"allowed": true,
"reason": null
},
"canSetCatchAll": {
"allowed": true,
"reason": null
}
},
"createOutcome": {
"status": "completed",
"reason": null,
"createdRuleCount": 1,
"createdRules": [
{
"id": "ef_01hxa3b4c5d6e7f8g9h0j1k2m3",
"email": "hello@example.com",
"destination": "owner@example.net",
"isEnabled": true,
"name": "hello",
"priority": 0
}
]
}
}
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.
createOutcomeobject
createdRuleCountinteger
createdRulesarray of object
idstring
emailstring
destinationstring
isEnabledboolean
namestring or null
priorityinteger

Errors

Errors are Problem Details with a stable code. Branch on the code, not on the text.

400The body is not valid, the recipients would create a forwarding loop (email_forwarding_loop) or the domain has no room for another rule.
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.
409The address already has a rule (email_in_use), the domain’s DNS is not at Hostup (domain_not_eligible) or another forwarding change is running (email_forwarding_busy).
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 did not answer or refused the change (external_provider_failed). Read the forwarding state before trying again.