Update domain email forwarding rule recipients

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

Replace the recipients of one domain-level email forwarding rule.

Get {id} from GET /api/v2/domains data[].id and {ruleId} from GET /api/v2/domains/{id}/email-forwarding rules[].id; {ruleId} must be the public ef_... ID.

The body may contain only destinations.

The source address of a rule cannot be changed: delete the rule with DELETE /api/v2/domains/{id}/email-forwarding/{ruleId} and create a new one.

Recipients that are not verified yet are registered and sent a verification email; the response then reports createOutcome.status: "verification_required" and the rule keeps forwarding to its current recipients until the request is repeated after verification.

Rules managed outside the forwarding editor cannot be edited and return 409 email_forwarding_not_editable.

The response is the refreshed forwarding state, the same shape as POST /api/v2/domains/{id}/email-forwarding.

Domains & DNS Email Forwarding

Authentication

Required API scopes: write:emailwrite:domains

Authenticate with an API key in the Authorization: Bearer <token> header.

Context

Path Parameters

id string required Example: dom_01hxa3b4c5d6e7f8g9h0j1k2m3

Public domain ID from GET /api/v2/domains data[].id. Do not invent this value; use the exact ID returned by the referenced API response.

ruleId string required Example: dom_01hxa3b4c5d6e7f8g9h0j1k2m3

Public email-forwarding rule ID from rules[].id. Do not invent this value; use the exact ID returned by the referenced API response.

Headers

Authorization Bearer <token>
Accept application/json
Content-Type application/json

Body

required
application/json
destinations array<string> required · Example: ["[email protected]","[email protected]"]

The complete new recipient list for the rule; addresses not listed stop receiving mail.

Responses

200 Recipients replaced, or verification requested for a new recipient. Refreshed forwarding state.
enabled boolean · Example: true
integrationStatus string · enum · Example: enabled
enabled
disabled
unavailable
reason string · nullable · Example: null

maxRules integer · Example: 200
ruleCount integer · Example: 1
rules array<object>
rules[].id string required · Example: ef_01hxa3b4c5d6e7f8g9h0j1k2m3
rules[].email string required · Example: [email protected]
rules[].destination string required · Example: [email protected]
rules[].isEnabled boolean required · Example: true
rules[].name string · nullable required · Example: null

Nullable: may be null when not applicable.

rules[].priority integer required · Example: 0
destinations array<object>
destinations[].id string required · Example: efd_01hxa3b4c5d6e7f8g9h0j1k2m3
destinations[].email string required · Example: [email protected]
destinations[].verificationStatus string · enum required · Example: verified
verified
pending
unverified
destinations[].createdAt string · nullable required · Example: 2026-04-27T12:00:00.000Z

Nullable: may be null when not applicable.

destinations[].verifiedAt string · nullable required · Example: 2026-04-27T12:05:00.000Z

Nullable: may be null when not applicable.

catchAll object | null · Example: {"action":"disabled","destination":null}
catchAll.action string · enum required · Example: disabled
forward
drop
disabled
catchAll.destination string · nullable required · Example: null

Nullable: may be null when not applicable.

existingMxRecords array<object>
existingMxRecords[].type string · enum required · Example: MX
MX
existingMxRecords[].value string required · Example: mail.example.com
existingMxRecords[].priority integer · nullable required · Example: 10

Nullable: may be null when not applicable.

dnsActivation object

Live state of the managed DNS zone this integration runs on. active: routing can be enabled now. activating: the domain already points at our nameservers and the zone is being activated — reading this resource requests the activation check, so poll until active (usually minutes). not_delegated: the domain's nameservers are elsewhere. unavailable: no managed zone, or the status could not be read.

dnsActivation.status string · enum required · Example: activating
active
activating
not_delegated
unavailable
dnsActivation.reason string · nullable required · Example: The domain points at our nameservers and its DNS zone is being activated. This usually ...

Plain-English explanation for every non-active status; null when active.

dnsActivation.checkedAt string required · Example: 2026-08-22T12:00:00.000Z
actions object
actions.canCreateNewRule object required
actions.canCreateNewRule.allowed boolean required · Example: true
actions.canCreateNewRule.reason string · nullable required · Example: null

Nullable: may be null when not applicable.

actions.canCreateNewRule.code string · nullable · Example: pending_order

Machine-readable reason code when an action is blocked.

actions.canSetCatchAll object required
actions.canSetCatchAll.allowed boolean required · Example: true
actions.canSetCatchAll.reason string · nullable required · Example: null

Nullable: may be null when not applicable.

actions.canSetCatchAll.code string · nullable · Example: pending_order

Machine-readable reason code when an action is blocked.

createOutcome object
createOutcome.createdRuleCount integer required · Example: 1
createOutcome.createdRules array<object> required
createOutcome.createdRules[].id string required · Example: ef_01hxa3b4c5d6e7f8g9h0j1k2m3
createOutcome.createdRules[].email string required · Example: [email protected]
createOutcome.createdRules[].destination string required · Example: [email protected]
createOutcome.createdRules[].isEnabled boolean required · Example: true
createOutcome.createdRules[].name string · nullable required · Example: null

Nullable: may be null when not applicable.

createOutcome.createdRules[].priority integer required · Example: 0
400 The body contains something other than destinations, or a recipient is invalid.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
401 Unauthorized. Authentication is required.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
403 Forbidden. The caller lacks a required scope or does not own the resource.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
404 Unknown domain, forwarding not configured for the domain, or unknown rule ID.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
409 The rule cannot be changed right now.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
429 Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
500 Internal error. Retry later or contact support if the issue persists.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
502 The email provider did not confirm the change.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
PATCH https://cloud.hostup.se/api/v2/domains/{id}/email-forwarding/{ruleId}
For AI assistants
View as Markdown
cURL 
curl -X PATCH "https://cloud.hostup.se/api/v2/domains/dom_01hxa3b4c5d6e7f8g9h0j1k2m3/email-forwarding/dom_01hxa3b4c5d6e7f8g9h0j1k2m3" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "destinations": [
      "[email protected]",
      "[email protected]"
    ]
  }'
Response 
// Change applied
{
  "enabled": true,
  "integrationStatus": "enabled",
  "reason": null,
  "maxRules": 200,
  "ruleCount": 1,
  "rules": [
    {
      "id": "ef_01hxa3b4c5d6e7f8g9h0j1k2m3",
      "email": "[email protected]",
      "destination": "[email protected]",
      "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"
    }
  ],
  "catchAll": {
    "action": "disabled",
    "destination": null
  },
  "existingMxRecords": [],
  "actions": {
    "canCreateNewRule": {
      "allowed": true,
      "reason": null
    },
    "canSetCatchAll": {
      "allowed": true,
      "reason": null
    }
  },
  "createOutcome": {
    "createdRuleCount": 0,
    "createdRules": []
  }
}

// New recipient must verify first; existing forwarding unchanged
{
  "enabled": true,
  "integrationStatus": "enabled",
  "reason": null,
  "maxRules": 200,
  "ruleCount": 1,
  "rules": [
    {
      "id": "ef_01hxa3b4c5d6e7f8g9h0j1k2m3",
      "email": "[email protected]",
      "destination": "[email protected]",
      "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"
    }
  ],
  "catchAll": {
    "action": "disabled",
    "destination": null
  },
  "existingMxRecords": [],
  "actions": {
    "canCreateNewRule": {
      "allowed": true,
      "reason": null
    },
    "canSetCatchAll": {
      "allowed": true,
      "reason": null
    }
  },
  "createOutcome": {
    "createdRuleCount": 0,
    "createdRules": [],
    "status": "verification_required",
    "destinationsNeedingVerification": [
      "[email protected]"
    ],
    "verificationEmailsSent": [
      "[email protected]"
    ],
    "reason": "Verify the new recipients, then save again. Existing forwarding remains unchanged."
  }
}
Request Body Forward to two addresses 
{
  "destinations": [
    "[email protected]",
    "[email protected]"
  ]
}