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
accountIdstringrequiredacct_…).Query parameters
domainstringrequiredExample
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.
{ "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
domainstringincomingobjectimapobjecthostnamestringportintegerencryptionstringssl_tls: encrypted from the start. starttls: connect, then upgrade with STARTTLS. One of ssl_tls, starttls.pop3objecthostnamestringportintegerencryptionstringssl_tls: encrypted from the start. starttls: connect, then upgrade with STARTTLS. One of ssl_tls, starttls.outgoingobjectsmtparray of objectssl_tls or port 587 with starttls.hostnamestringportintegerencryptionstringssl_tls: encrypted from the start. starttls: connect, then upgrade with STARTTLS. One of ssl_tls, starttls.usernameFormatstringfull_email_address: the username is the whole address, such as info@example.com. One of full_email_address.webmailUrlstringhttps://webmail.<domain> when a live check verified it. Otherwise the server’s webmail address on port 2096.alternativeHostnamestringmail.<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 nullmail.<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 stringErrors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | The domain query parameter is missing or is not a valid domain (invalid_request). |
| 401 | Unauthorized. Authentication is required. |
| 403 | The key lacks a scope or the account is not active. domain_not_owned: the domain is not on this account. |
| 404 | Not found. The resource does not exist or is not owned by the caller. |
| 409 | The account is on Hostup’s previous hosting platform (account_not_eligible_cpanel). Mail app settings are only given for accounts on 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 account’s domains could not be read to check domain (upstream_failed). Try again later. |