Skip to content

Create an email account

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

Creates a mailbox on the web hosting account. Send the address as localPart and domain. The domain must be on the account. Check actions.canCreate on GET /api/v2/shared-hosting/{accountId}/email-accounts first. This call does not check it. Past the plan’s mailbox limit it fails with 502 upstream_failed. Sending it again fails the same way. The password must be 8-128 characters and contain uppercase, lowercase, and a number. It must also be hard to guess. A password that breaks these rules returns 400 password_too_weak. Without quotaMb the mailbox gets 32768 MB (32 GB). 0 means no limit. An address that already exists returns 409 email_in_use. An account on Hostup’s previous hosting platform returns 409 account_not_eligible_cpanel.

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 before @, for example hello in hello@example.com. Letters, digits and ._%+-, at most 64 characters.
domainstringrequired
Domain on the hosting account. Unicode IDN and punycode spellings are both accepted.
passwordstringrequired
Mailbox password, 8-128 characters with uppercase, lowercase and a number. It must be hard to guess.
quotaMbnumber
Mailbox quota in MB, 0–1048576. Default 32768 (32 GB). 0 means no limit. 0 to 1048576.

Example

POST /api/v2/shared-hosting/{accountId}/email-accounts
curl -X POST "https://cloud.hostup.se/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/email-accounts" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"localPart": "hello",
"domain": "example.com",
"password": "Tall-Harbor-58-Lantern",
"quotaMb": 1024
}'

Responses

201 The mailbox is created.

Response 201
{
"id": "mail_01hxa3b4c5d6e7f8g9h0j1k2m3",
"email": "hello@example.com",
"domain": "example.com",
"quota": {
"usedGb": 0,
"limitGb": 1,
"usagePercent": 0,
"exceeded": false
}
}
Response fields
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
The requested quota. usedGb is 0 for a new mailbox.
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.

Errors

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

400The body is invalid (invalid_request). A password that breaks the rules returns password_too_weak with minimumScore. A password that is too easy to guess also gets score and suggestions.
401Unauthorized. Authentication is required.
403The mailbox 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 mailbox already exists (email_in_use) or the account is on Hostup’s previous hosting platform (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 server did not create the mailbox (upstream_failed). The plan’s mailbox limit also gives this code. A retry then fails the same way. Check actions.canCreate on GET /api/v2/shared-hosting/{accountId}/email-accounts before you try again.