Skip to content
HostupDevelopers
GuidesAPI referenceSupport

Change forwarding rule recipients

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

Replaces the recipient list of one forwarding rule. The forwarding address itself cannot change. To use another address, delete the rule and create a new one with POST /api/v2/domains/{id}/email-forwarding. A new recipient address gets a verification e-mail. While any recipient in the list is unverified, nothing changes and createOutcome.status is verification_required. Send the same request again once every recipient has verified. To send a recipient the e-mail again, use POST /api/v2/domains/{id}/email-forwarding/destinations/{destinationId}/verification. Returns the domain’s forwarding settings with the updated rule.

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

Request

Path parameters

idstringrequired
The domain ID (dom_…).
ruleIdstringrequired
The forwarding rule ID (ef_…) from rules[].id on GET /api/v2/domains/{id}/email-forwarding.

Body

destinationsarray of stringrequired
The complete new recipient list, 1 to 10 addresses. Addresses left out stop receiving mail.

Example

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

Responses

200 The change was saved or a new recipient must verify first (createOutcome.status). The body is the domain’s forwarding settings.

{
  "enabled": true,
  "integrationStatus": "enabled",
  "reason": null,
  "maxRules": 200,
  "ruleCount": 1,
  "rules": [
    {
      "id": "ef_01hxa3b4c5d6e7f8g9h0j1k2m3",
      "email": "[email protected]",
      "destination": "[email protected]",
      "destinations": [
        "[email protected]",
        "[email protected]"
      ],
      "editable": true,
      "isEnabled": true,
      "name": "hello",
      "priority": 0
    }
  ],
  "destinations": [
    {
      "id": "efd_01hxa3b4c5d6e7f8g9h0j1k2m3",
      "email": "[email protected]",
      "verificationStatus": "verified",
      "createdAt": "2026-04-27T12:00:00.000Z",
      "verifiedAt": "2026-04-27T12:05:00.000Z"
    },
    {
      "id": "efd_01hxb4c5d6e7f8g9h0j1k2m3n4",
      "email": "[email protected]",
      "verificationStatus": "verified",
      "createdAt": "2026-04-27T12:00:00.000Z",
      "verifiedAt": "2026-04-27T12:06: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": 0,
    "createdRules": []
  }
}
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 has a field other than destinations, a recipient is invalid or the recipients would forward mail in a loop (email_forwarding_loop).
401Unauthorized. Authentication is required.
403Forbidden. The caller lacks a required scope or does not own the resource.
404The domain, the rule or the domain’s forwarding setup was not found.
409email_forwarding_not_editable: the rule was set up outside the forwarding settings (rules[].editable is false). email_forwarding_busy: another forwarding change on the domain is still running.
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 confirm the change. Read the rule list before you retry.

This page as MarkdownOpenAPI spec