Skip to content

Create an email forwarder

POST /api/v2/shared-hosting/{accountId}/email-forwarders

Creates a forwarder on the web hosting account: mail to the source address goes to one to twenty other addresses. Send the source address as localPart and domain. The domain must be on the account. action: discard instead makes an address that drops its mail, for example noreply. Check actions.canCreate on GET /api/v2/shared-hosting/{accountId}/email-forwarders first. This call does not check it. For a domain without web hosting use POST /api/v2/domains/{id}/email-forwarding. Use PUT /api/v2/domains/{id}/email-forwarding for catch-all forwarding on such a domain. An account on Hostup’s previous hosting platform returns 409 account_not_eligible_cpanel. Its forwarder list still shows actions.canCreate.allowed as true.

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

Request

Path parameters

accountIdstringrequired
The hosting account ID (acct_…).

Body

localPartstringrequired
The part of the source address before @, for example info in info@example.com. Letters a–z and A–Z, digits and . _ % + -, up to 64 characters.
domainstringrequired
Source domain on the hosting account. Unicode IDN and punycode spellings are both accepted.
destinationsarray of string
Addresses to forward to, 1–20. Leave out for discard.
destinationstringdeprecated
A singular destination string is accepted as an alias for one address. Use destinations instead; do not send both fields.
actionstring
forward (default) sends the mail on. discard drops it. One of forward, discard.

Example

POST /api/v2/shared-hosting/{accountId}/email-forwarders
curl -X POST "https://cloud.hostup.se/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/email-forwarders" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"localPart": "info",
"domain": "example.com",
"action": "forward",
"destinations": [
"anna@example.net"
]
}'

Responses

201 The forwarder is created.

Response 201
{
"id": "efwd_01hxa3b4c5d6e7f8g9h0j1k2m3",
"email": "info@example.com",
"domain": "example.com",
"localPart": "info",
"action": "forward",
"destinations": [
"anna@example.net"
]
}
Response fields
idstring
Forwarder ID (efwd_…). Paths accept it in place of the source address.
emailstring
Source address. IDNs are in Unicode form.
domainstring
Source domain. IDNs are in Unicode form.
localPartstring
The part of the source address before @.
actionstring
forward sends the mail to destinations. discard drops it. One of forward, discard.
destinationsarray of string
Addresses the mail goes to. Empty for discard.

Errors

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

400The body is invalid: a missing or bad localPart or domain, no destination for forward, more than 20 destinations, a destination that is not an email address, destinations with discard or both destination and destinations. A missing or bad localPart returns the detail “Invalid request body.” with the pointer /body. That detail does not name the field.
401Unauthorized. Authentication is required.
403The source domain is not on this hosting account (domain_not_owned), the API key lacks a required scope or the account is not active.
404Not found. The resource does not exist or is not owned by the caller.
409The account is on Hostup’s previous hosting platform. Forwarders cannot be managed there through the API.
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 server did not create the forwarder. detail does not say why. Check actions.canCreate and the existing forwarders on GET /api/v2/shared-hosting/{accountId}/email-forwarders before you try again.