docs(email): document mail-client autodiscovery + external-DNS records

Reflects the new customer "Mail Client Setup" section on the Email page.

- create-an-email-account.mdx: new "Auto-configure your mail app" section —
  explains clients self-configure from DNS, that domains on our nameservers
  are already set, and the records to add when DNS is hosted elsewhere
  (Cloudflare/GoDaddy/etc.) with the full RFC 6186 record table + screenshot.
  Reframe "Set up your email client" as the manual fallback.
- manage-dns-records.mdx: cross-link "Mail autodiscovery records" subsection.
- New capture-email.ts + whp-email-autodiscovery.png (fleet-redacted: mail
  host shown as <mail-server>.cloud-hosting.io; demo domain kept visible).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-22 08:11:44 -07:00
parent 03aa273100
commit 0b53569821
4 changed files with 144 additions and 1 deletions
Binary file not shown.

After

Width:  |  Height:  |  Size: 369 KiB

@@ -34,9 +34,41 @@ import Support from '~/content/partials/support-link.mdx';
</Steps>
## Auto-configure your mail app
Most modern mail apps — Outlook, Apple Mail, Thunderbird, and the iOS and Android mail apps — can set themselves up from your domain's DNS. You enter your **full email address** and **password**, and the app finds the right servers, ports, and security settings on its own.
**If your domain uses our nameservers, this already works** — we add the necessary records automatically when you add the domain, so there's nothing for you to do.
### If your DNS is hosted elsewhere
If your domain's DNS lives at another provider (Cloudflare, GoDaddy, Namecheap, and so on), your mail app can't auto-configure until you add a few records there yourself. The Email page builds the exact records for you: open the **Mail Client Setup** section, pick the domain, and copy them in.
![The Mail Client Setup section on the WHP Email page, showing autodiscovery DNS records for a domain](~/assets/screenshots/whp/whp-email-autodiscovery.png)
Add these records to the domain's zone at your DNS provider. The names are **relative to your domain** — most providers fill in the rest automatically, so `autoconfig` becomes `autoconfig.example.com`.
| Type | Name | Priority | Weight | Port | Value |
| --- | --- | --- | --- | --- | --- |
| CNAME | `autoconfig` | — | — | — | your mail server |
| SRV | `_autodiscover._tcp` | 0 | 0 | 443 | your mail server |
| SRV | `_imaps._tcp` | 0 | 1 | 993 | your mail server |
| SRV | `_submission._tcp` | 0 | 1 | 587 | your mail server |
| SRV | `_pop3s._tcp` | 0 | 1 | 995 | your mail server |
Use the **mail server hostname shown in the Mail Client Setup section** as the value — it's the same host your **MX** record points at. The `_pop3s` record is only needed if you read mail over POP3 instead of IMAP. Click **Copy records** to grab them all at once in zone-file format.
<Aside type="tip">
If your provider has a proxy toggle (such as Cloudflare's orange cloud), keep these records **DNS only** — proxying them stops mail clients from reading them.
</Aside>
<Aside type="note">
These records only help apps *find* the server. You still create the mailbox in WHP first, and your domain's **MX** record must point at our mail server for mail to be delivered.
</Aside>
## Set up your email client
The exact IMAP, POP3, and SMTP hostnames are listed on the Email page click **Setup Instructions → View Instructions** under **Mail Server Access** for a step-by-step that includes the right hostnames, ports, and security settings for your server.
Most apps configure themselves from the records above once you enter your address and password. If yours doesn't support that — or you'd rather enter the settings by hand — the exact IMAP, POP3, and SMTP hostnames are listed on the Email page: click **Setup Instructions → View Instructions** under **Mail Server Access** for a step-by-step that includes the right hostnames, ports, and security settings for your server.
The typical settings look like this; substitute the hostname shown in the Setup Instructions:
@@ -48,6 +48,12 @@ Each domain starts with a standard zone created automatically when the domain wa
Editing **MX**, **NS**, or the SPF/DKIM **TXT** records can break email delivery or hand DNS control away from us. Only change these if you know exactly what you're doing.
</Aside>
## Mail autodiscovery records
When we host your DNS, the records that let mail apps configure themselves — an `autoconfig` CNAME plus a set of `_autodiscover` / `_imaps` / `_submission` / `_pop3s` **SRV** records — are already in your zone. You don't need to add them.
If your DNS is at another provider, add them there by hand. WHP builds the exact records for each domain on the **Email** page — see [Auto-configure your mail app](/whp/how-to/create-an-email-account/#auto-configure-your-mail-app).
## Add a record
<Steps>