Skip to content

Set the email catch-all

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

Sets what happens to mail for addresses on the domain that have no forwarding rule. forward sends it to forwardTo. drop discards it without notice. fail turns the catch-all off, shown as disabled in the response. This is part of the domain’s email forwarding, for a domain whose DNS is at Hostup. A web hosting account handles this in its own mail settings, shown by GET /api/v2/shared-hosting/{accountId}/email-default-address. The forwardTo address must be verified. If it is not, the call sends a verification e-mail and returns 409 destination_verification_required. Send the request again after the recipient has clicked the link. The response is the catch-all only, not the whole forwarding state.

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

actionstringrequired
forward sends unmatched mail to forwardTo. drop discards it. fail turns the catch-all off. One of forward, drop, fail.
forwardTostring
The address to forward unmatched mail to. Required when action is forward.

Example

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

Responses

200 The catch-all after the change.

Response 200
{
"action": "forward",
"destination": "owner@example.net"
}
Response fields
actionstring
forward, drop or disabled. One of forward, drop, disabled.
destinationstring or null
Where unmatched mail goes when action is forward. Otherwise null.

Errors

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

400The body is not valid. action must be forward, drop or fail. forwardTo must be a valid address when action is forward.
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.
409forwardTo has not been verified yet (destination_verification_required), the DNS zone is still activating (dns_zone_activating) or the domain’s DNS is not at Hostup (domain_not_eligible).
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).