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
accountIdstringrequiredacct_…).Body
localPartstringrequired@, for example hello in hello@example.com. Letters, digits and ._%+-, at most 64 characters.domainstringrequiredpasswordstringrequiredquotaMbnumber0 means no limit. 0 to 1048576.Example
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.
{ "id": "mail_01hxa3b4c5d6e7f8g9h0j1k2m3", "email": "hello@example.com", "domain": "example.com", "quota": { "usedGb": 0, "limitGb": 1, "usagePercent": 0, "exceeded": false }}Response fields
idstringmail_…). Paths accept it in place of the address.emailstringdomainstringquotaobjectusedGb is 0 for a new mailbox.usedGbnumber or nullnull when the server gave no usable reading.limitGbnumber or nullnull when the mailbox has no limit.usagePercentnumber or nullnull without a limit or a reading.exceededbooleantrue 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.
| 400 | The 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. |
| 401 | Unauthorized. Authentication is required. |
| 403 | The mailbox domain is not on this hosting account (domain_not_owned), the API key lacks a required scope or the account is not active. |
| 404 | Not found. The resource does not exist or is not owned by the caller. |
| 409 | The mailbox already exists (email_in_use) or the account is on Hostup’s previous hosting platform (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 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. |