Update domain email catch-all

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

Configure the domain-level catch-all behavior for unmatched addresses.

Get {id} from GET /api/v2/domains data[].id.

This is part of domain email forwarding, not shared-hosting forwarders, and there is no /api/v2/shared-hosting/{accountId}/catch-all route.

If the domain is attached to a shared-hosting account and you want hosting mailboxes/forwarders to keep handling mail, manage forwarding through /api/v2/shared-hosting/{accountId}/email-forwarders instead.

Send action: "forward" with forwardTo to forward all unmatched mail, action: "drop" to silently discard unmatched mail, or action: "fail" to disable/fail unmatched delivery.

A forward destination must be a verified forwarding destination: if it is not verified yet, the request sends (or re-sends) the verification email and returns 409 destination_verification_required — the recipient clicks the link, then the request succeeds on retry.

The response is the refreshed catch-all object, not the full forwarding state.

Domains & DNS Email Forwarding

Authentication

Required API scopes: write:emailwrite:domains

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

Context

Related endpoints

GET /api/v2/domains/{id}/email-forwarding Get domain email forwarding PATCH /api/v2/domains/{id}/email-forwarding Toggle domain email forwarding POST /api/v2/domains/{id}/email-forwarding Create domain email forwarding rule

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.

Headers

Authorization Bearer <token>

Accept application/json

Content-Type application/json

Body

required

application/json

action string · enum required · Example: forward

fail is the v2 public label for disabling the catch-all route.

forward

drop

fail

forwardTo string · Example: owner@example.net

Required only when action is forward.

Responses

200 Refreshed catch-all state. 2 fields

action string · enum required · Example: forward

forward

drop

disabled

destination string · nullable required · Example: owner@example.net

400 Invalid request. The response body is an RFC 7807 Problem Details document. 10 fields

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. 10 fields

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. 10 fields

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 Not found. The resource does not exist or is not owned by the caller. 10 fields

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 catch-all cannot be updated in the current state: the forward destination has not confirmed its verification email yet, or the domain's DNS zone is still being set up. 10 fields

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. 10 fields

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. 10 fields

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

PUT https://cloud.hostup.se/api/v2/domains/{id}/email-forwarding

For AI assistants

View as Markdown

Scenario

cURL

curl -X PUT "https://cloud.hostup.se/api/v2/domains/dom_01hxa3b4c5d6e7f8g9h0j1k2m3/email-forwarding" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "forward",
    "forwardTo": "owner@example.net"
  }'

Response

{
  "action": "forward",
  "destination": "owner@example.net"
}

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "forward",
        "drop",
        "disabled"
      ]
    },
    "destination": {
      "type": "string",
      "nullable": true
    }
  }
}

Request Body Forward all unmatched mail

{
  "action": "forward",
  "forwardTo": "owner@example.net"
}