One major drawback of offering your own IMAP/SMTP-based email service is that users need to enter a long list of details to set up their email client. Unfortunately there is no unified technique to make this step easier. You can still cover a good number of email clients by following the techniques below. This only covers the basic use case and you may want to look up further details if your use case is more specialized.
Microsoft Outlook 🔗
Up until Outlook 2016, there was support for autodiscover.xml: Outlook would look up autodiscover.domain.com and then do a POST request to /autodiscover/autodiscover.xml including the email to set up.
Unfortunately, Outlook 2016 introduced a simplified dialog, which relies on SRV entries to discover services and doesn’t allow specifying a username. I didn’t get SRV entries for IMAP servers to work with Outlook thus far.
To use the full dialog, you can add the following entry (save as DisableOffice365SimplifiedAccountCreation.reg) to the registry and after restarting Outlook, you will get the full dialog back.
Windows Registry Editor Version 5.00
[HKEY_CURRENT_USER\Software\Microsoft\Office\16.0\Outlook\Setup]
"DisableOffice365SimplifiedAccountCreation"=dword:00000001
Mozilla Thunderbird 🔗
Thunderbird has well-documented1 support for a protocol called “Autoconfig”. First it will look for a subdomain autoconfig.domains.com and then GET /mail/config-v1.1.xml?emailaddress=user@domain.com. It then expects a XML file similar to Outlook.
I found this setup to work well and not other steps are needed. They hope to add support for setting up CalDAV, CardDAV, etc in the future.
Apple Mail (iOS and macOS) 🔗
Apple Mail has no direct autoconfig support, but you can use mobile configuration profiles to add accounts. This requires the user to visit a website, but has the advantage that you can also configure CalDAV and CardDAV. To pre-fill the profile with the correct details, you could use a personalized URL, simple web form or basic auth. After adding their details, you offer a .mobileconfig file with MIME type application/x-apple-aspen-config for download.
There is also a dedicated app2 to verify and create configuration profiles. So one only needs to fill in the changing parts.
Implementation 🔗
Populating and serving those XML files needs some minimal processing on the server. You may also want to connect to Active Directory or LDAP to look up user details. PHP works well for this and there is a Github repo which covers all three providers as starting point3. Since every deployment is different, it’s best to use this repo as starting point and customize for your own needs.