Skip to content

Set email routing for a domain

PUT /api/v2/shared-hosting/{accountId}/email-routing

Set how incoming mail is routed for a domain on a web hosting account. Use remote when an outside mail provider handles the domain’s mail. Use local to deliver it to mailboxes on this account. The domain must be on this account. Otherwise the call returns 403 domain_not_owned. The account must be active and on cPanel. The response is the routing read back after the change.

Authentication: An API key with the scopes write:hosting and console:services. About keys and scopes

Request

Path parameters

accountIdstringrequired
The web hosting account ID (acct_…).

Body

domainstringrequired
The domain on the account, in Unicode or punycode form.
modestringrequired
local: deliver to mailboxes on this account. remote: an outside mail provider receives the mail. secondary: this account is a backup mail server. auto: the server picks from the domain’s MX records. One of auto, local, secondary, remote.

Example

PUT /api/v2/shared-hosting/{accountId}/email-routing
curl -X PUT "https://cloud.hostup.se/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/email-routing" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"domain": "example.com",
"mode": "remote"
}'

Responses

200 The routing after the change.

Response 200
{
"id": "eroute_01hxa3b4c5d6e7f8g9h0j1k2m3",
"domain": "example.com",
"mode": "remote",
"detectedMode": null
}
Response fields
idstring
ID of this routing setting (eroute_…).
domainstring
The domain, in Unicode form.
modestring
How incoming mail for the domain is delivered. local: to mailboxes on this account. remote: to an outside mail provider. secondary: this account acts as a backup mail server. auto: the server picks from the domain’s MX records. One of auto, local, secondary, remote.
detectedModestring or null
The mode the server detected from the domain’s MX records, when it reports one. One of auto, local, secondary, remote.

Errors

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

400Invalid request. The response body is an RFC 7807 Problem Details document.
401Unauthorized. Authentication is required.
403The key lacks a scope or the account is not active. domain_not_owned: the domain is not on this account.
404Not found. The resource does not exist or is not owned by the caller.
409The account is not on cPanel, where email routing is not available (account_not_eligible_cpanel).
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 routing could not be changed right now (upstream_failed). Read it with GET before you retry.