Skip to content

List email forwarders

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

Lists the email forwarders on the web hosting account, with how many more the plan allows. A forward row lists its destinations. A discard row drops the mail and has no destinations. Forwarding set up on a domain without web hosting is under GET /api/v2/domains/{id}/email-forwarding. On an account on Hostup’s previous hosting platform the list is empty. Creating a forwarder there returns 409 account_not_eligible_cpanel.

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

Request

Path parameters

accountIdstringrequired
The hosting account ID (acct_…).

Query parameters

domainstring
Only forwarders on this domain. Unicode IDN and punycode spellings are both accepted.

Example

GET /api/v2/shared-hosting/{accountId}/email-forwarders
curl "https://cloud.hostup.se/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/email-forwarders" \
-H "Authorization: Bearer $HOSTUP_API_KEY"

Responses

200 Forwarders on the account.

Response 200
{
"forwarders": [
{
"id": "efwd_01hxa3b4c5d6e7f8g9h0j1k2m3",
"email": "info@example.com",
"domain": "example.com",
"localPart": "info",
"action": "forward",
"destinations": [
"anna@example.net"
]
}
],
"quota": {
"used": 1,
"limit": null,
"remaining": null
},
"actions": {
"canCreate": {
"allowed": true,
"reason": null
}
}
}
Response fields
forwardersarray of object
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.
quotaobject
Forwarders used and allowed by the plan.
usedinteger
Forwarders on the account.
limitinteger or null
Forwarders the plan allows. null when there is no limit or it could not be read.
remaininginteger or null
Forwarders left. null when limit is null.
actionsobject
canCreateobject
Whether another forwarder can be created, with the reason when it cannot.
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.

Errors

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

400The domain filter is not a valid domain name.
401Unauthorized. Authentication is required.
403The API key lacks a required scope or the hosting account is not active.
404Not found. The resource does not exist or is not owned by the caller.
409Conflict. code is account_suspended, 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.
502Upstream failure. A dependent provider request failed; the Problem Details code is upstream_failed. Retry later or contact support if the issue persists.