Skip to content

Get mail app settings for a domain

GET /api/v2/shared-hosting/{accountId}/mail-settings

Returns what a mail app needs for the mailboxes of one domain on a web hosting account. That is the IMAP, POP3 and SMTP servers with their ports and encryption, plus the webmail address. The username is always the full email address. The password is the mailbox password. verifiedDomainHostname is mail.<domain> when a live check found that it points at the account’s server with a valid certificate. Use it when it is set. It keeps working if the account moves to another server. Otherwise use the server host name in incoming and outgoing. The domain must be on the account (403 domain_not_owned). The account must be active and on cPanel.

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

Request

Path parameters

accountIdstringrequired
The web hosting account ID (acct_…).

Query parameters

domainstringrequired
The domain on the account, in Unicode or punycode form.

Example

GET /api/v2/shared-hosting/{accountId}/mail-settings
curl "https://cloud.hostup.se/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/mail-settings?domain=example.com" \
-H "Authorization: Bearer $HOSTUP_API_KEY"

Responses

200 Mail app settings for the domain.

Response 200
{
"domain": "example.com",
"incoming": {
"imap": {
"hostname": "server.example.net",
"port": 993,
"encryption": "ssl_tls"
},
"pop3": {
"hostname": "server.example.net",
"port": 995,
"encryption": "ssl_tls"
}
},
"outgoing": {
"smtp": [
{
"hostname": "server.example.net",
"port": 465,
"encryption": "ssl_tls"
},
{
"hostname": "server.example.net",
"port": 587,
"encryption": "starttls"
}
]
},
"usernameFormat": "full_email_address",
"webmailUrl": "https://webmail.example.com",
"alternativeHostname": "mail.example.com",
"verifiedDomainHostname": "mail.example.com",
"notes": [
"Sign in with the full email address as the username and the mailbox password as the password — the same login works for webmail.",
"mail.example.com can be used instead of server.example.net for the incoming and outgoing servers, but its certificate depends on the domain's SSL setup. If the mail app shows a certificate or security warning, use server.example.net — it always has a valid certificate.",
"Use IMAP rather than POP3 when the mailbox is read on more than one device — IMAP keeps mail on the server and in sync."
]
}
Response fields
domainstring
The domain, in Unicode form.
incomingobject
Servers for receiving mail.
imapobject
The IMAP server.
hostnamestring
The server’s host name. It always has a valid certificate.
portinteger
Port number.
encryptionstring
ssl_tls: encrypted from the start. starttls: connect, then upgrade with STARTTLS. One of ssl_tls, starttls.
pop3object
The POP3 server.
hostnamestring
The server’s host name. It always has a valid certificate.
portinteger
Port number.
encryptionstring
ssl_tls: encrypted from the start. starttls: connect, then upgrade with STARTTLS. One of ssl_tls, starttls.
outgoingobject
Servers for sending mail.
smtparray of object
Two SMTP options. Either works: port 465 with ssl_tls or port 587 with starttls.
hostnamestring
The server’s host name. It always has a valid certificate.
portinteger
Port number.
encryptionstring
ssl_tls: encrypted from the start. starttls: connect, then upgrade with STARTTLS. One of ssl_tls, starttls.
usernameFormatstring
Always full_email_address: the username is the whole address, such as info@example.com. One of full_email_address.
webmailUrlstring
Webmail in the browser, for the same mailboxes and login. https://webmail.<domain> when a live check verified it. Otherwise the server’s webmail address on port 2096.
alternativeHostnamestring
mail.<domain>. It can replace the server host name only when the domain’s certificate covers it. This value is not checked. Use verifiedDomainHostname for a checked name.
verifiedDomainHostnamestring or null
mail.<domain> when a live check found that every A and AAAA record points at the account’s server and the certificate is valid for it. The check is cached for up to 10 minutes. Null when the check failed or could not run.
notesarray of string
Setup advice in plain English, written for the mailbox user.

Errors

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

400The domain query parameter is missing or is not a valid domain (invalid_request).
401Unauthorized. Authentication is required.
403The key lacks a scope or the account is not active. domain_not_owned: the domain is not on this account.
404Not found. The resource does not exist or is not owned by the caller.
409The account is on Hostup’s previous hosting platform (account_not_eligible_cpanel). Mail app settings are only given for accounts on 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 account’s domains could not be read to check domain (upstream_failed). Try again later.