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
accountIdstringrequiredThe web hosting account ID (
acct_…).Body
domainstringrequiredThe domain on the account, in Unicode or punycode form.
modestringrequiredlocal: 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
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" }'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": "local" }'Responses
200 The routing after the change.
{ "id": "eroute_01hxa3b4c5d6e7f8g9h0j1k2m3", "domain": "example.com", "mode": "remote", "detectedMode": null}Response fields
idstringID of this routing setting (
eroute_…).domainstringThe domain, in Unicode form.
modestringHow 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 nullThe 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.
| 400 | Invalid request. The response body is an RFC 7807 Problem Details document. |
| 401 | Unauthorized. Authentication is required. |
| 403 | The key lacks a scope or the account is not active. domain_not_owned: the domain is not on this account. |
| 404 | Not found. The resource does not exist or is not owned by the caller. |
| 409 | The account is not on cPanel, where email routing is not available (account_not_eligible_cpanel). |
| 429 | Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers. |
| 500 | Internal error. Retry later or contact support if the issue persists. |
| 502 | The routing could not be changed right now (upstream_failed). Read it with GET before you retry. |