Skip to content

List email accounts

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

Lists the mailboxes on the web hosting account with the storage each one uses. It also says how many more the plan allows. Check actions.canCreate before you create a mailbox. Mailbox domains are returned in readable Unicode form. An account on Hostup’s previous hosting platform returns 409 account_not_eligible_cpanel. Support moves such an account to cPanel at no charge.

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

Request

Path parameters

accountIdstringrequired
The hosting account ID (acct_…).

Query parameters

domainstring
Only mailboxes on this domain. Unicode IDN and punycode spellings are both accepted. quota and actions still count the whole account.

Example

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

Responses

200 Mailboxes on the account.

Response 200
{
"emailAccounts": [
{
"id": "mail_01hxa3b4c5d6e7f8g9h0j1k2m3",
"email": "hello@example.com",
"domain": "example.com",
"quota": {
"usedGb": 0.125,
"limitGb": 32,
"usagePercent": 0.39,
"exceeded": false
}
}
],
"quota": {
"used": 1,
"limit": 10,
"remaining": 9
},
"actions": {
"canCreate": {
"allowed": true,
"reason": null
}
}
}
Response fields
emailAccountsarray of object
idstring
Email account ID (mail_…). Paths accept it in place of the address.
emailstring
Full email address. IDNs are in Unicode form.
domainstring
Mailbox domain. IDNs are in Unicode form.
quotaobject
Storage use against the mailbox quota.
usedGbnumber or null
Storage used in GB. null when the server gave no usable reading.
limitGbnumber or null
Mailbox quota in GB. null when the mailbox has no limit.
usagePercentnumber or null
Share of the quota used, 0–100. null without a limit or a reading.
exceededboolean
true when the storage used is above the quota.
quotaobject
Mailboxes used and allowed by the plan.
usedinteger
Mailboxes on the account.
limitinteger or null
Mailboxes the plan allows. null when there is no limit or it could not be read.
remaininginteger or null
Mailboxes left. null when limit is null.
actionsobject
canCreateobject
Whether another mailbox 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.
403forbidden. With requiredScopes in the body, the key lacks read:hosting. Without it, the hosting 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. Mailboxes cannot be listed 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 mailboxes could not be loaded from the server. Try again.