Mail clients & webmail
Your domain users have three ways to read and send mail, all ready as soon as a mail service exists:
- webmail in the browser
- a mail client that sets itself up
- a mail client you set up by hand
Everything they need is on the Setup Mail Application page of their sign-in portal.
Webmail
Webmail runs at your mail server domain, the one you chose when the mail service was created. There is nothing to set up and no separate password.
Signing in to webmail is signing in to the portal, so everything from the portal applies: two-factor authentication, passkeys, and your authentication policy. A webmail session appears in the user's session list like any other.
Automatic configuration
The mail service publishes the autodiscovery records that let a client set itself up from an email address and a password alone:
- autoconfig, as Thunderbird uses it
- autodiscover, as Microsoft uses it
- DNS service records pointing at the right servers and ports, including calendar and contact synchronization
For iOS and macOS there is an Apple configuration profile, a
.mobileconfig file the user downloads from the mail setup page. It sets
up mail, calendars, and contacts in one step.
Two kinds of password
How a client authenticates matters more than which client it is.
| Modern sign-in with OpenID Connect and OAuth | Traditional password authentication | |
|---|---|---|
| How it works | The client opens a browser window, and the user signs in there through the portal. | The client sends a username and password directly over IMAP, POP3, or SMTP. |
| Does the client learn the password? | No. | Yes. |
| Two-factor authentication and passkeys | Work. | Don't apply. |
| Visibility | The client appears under the user's connected apps, where they can revoke it. | The client doesn't appear. |
| Examples | Thunderbird offers this during automatic configuration. | Everything else, including the Apple profile. |
The user creates an app password in the portal, one per application, instead of using their main password. Your authentication policy can make this mandatory; a user under such a policy uses the Apple profile with an app password.
Almost always this: the user's policy doesn't accept the main password over the mail protocols, so the app needs an app password. The mail setup page tells the user so.
Manual settings
For clients that neither set themselves up nor support OAuth, the mail setup page lists the values with a copy button for each. The username is always the full email address; the password is the user's main password or an app password, as the policy decides.
| Protocol | Server | Port |
|---|---|---|
| SMTP, to send mail | your mail server domain | 587 with STARTTLS, or 465 with SSL/TLS |
| IMAP, recommended | your mail server domain | 993 with SSL/TLS, or 143 with STARTTLS |
| POP3 | your mail server domain | 995 with SSL/TLS, or 110 with STARTTLS |
| Contacts, with CardDAV | https://<mail server>/dav | 443 |
| Calendar, with CalDAV | https://<mail server>/dav | 443 |
- The server offers no unencrypted connection. On a STARTTLS port, the client has to make the upgrade.
- POP3 downloads mail and removes it from the server, so IMAP is the right default for anyone with more than one device.
Manual OpenID Connect or OAuth2 settings
For a client that supports OAuth2 but can't find the settings by itself, Manual OpenID Connect or OAuth2 Settings on the mail setup page holds the values for its advanced settings. They work for full OpenID Connect and for the OAuth2-only support many email applications have.
| Value | What to give the client |
|---|---|
| Client ID | The value on the page. |
| Client secret | None. Leave it empty; the client is a public application and has no secret. |
| Authorization endpoint and Token endpoint | The values on the page. |
| Scopes | The values on the page, separated by spaces. If the client asks for one scope per service, give only the ones it needs. |
| Redirect URI | http://127.0.0.1/, or empty if the client supplies its own. The client picks the port. An IPv6 client can use http://[::1]/. |
| Use PKCE | Yes. PKCE is required, because the client has no secret. |
| Use system web browser | Yes, where the client offers the choice. The browser then keeps the user signed in, and a passkey or security key works. |
| Issuer and Discovery URL | The values on the page. Some clients ask only for the discovery URL and find the endpoints themselves. |
The SASL mechanism is XOAUTH2 or OAUTHBEARER, for SMTP, IMAP, and POP3 alike. The page names it beside each protocol.
When a connection doesn't work
The Email Access Log records the networks, protocols, and app passwords each mailbox was accessed from. Look there when you're not sure as which user a client connects, or when you suspect a credential is used from somewhere it shouldn't be.
You can turn off a protocol for one domain user. See Account types. A client that fails on POP3 alone may be hitting that policy.