Have you ever worked with Thunderbird as a mail client? When you add a mail account you get a setup wizard like this:
You click on Continue and Thunderbird tries to find out which parameters are needed to connect to your mail server properly. But usually you just end up with this:
What is necessary to help Thunderbird (and other mail clients like Evolution, Kmail, Kontact or even Outl**k) with that? Unfortunately there is no official standard for it yet. But among other mail user agents Thunderbird has a couple of methods implemented to find out how the mail server for this domain can be reached.
For large ISPs they maintain their ISPDB database. But your market share may not be enough to be listed there. The next best option is to provide an XML file in a certain format through your web server. Thunderbird will look for this URL:
https://example.org/.well-known/autoconfig/mail/config-v1.1.xml
The syntax of the XML file is described here. A simple configuration file looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<clientConfig version="1.1">
<emailProvider id="workaround.org">
<domain>workaround.org</domain>
<displayName>Christoph's Mail Service</displayName>
<displayShortName>ISPmail</displayShortName>
<incomingServer type="imap">
<hostname>webmail.workaround.org</hostname>
<port>143</port>
<socketType>STARTTLS</socketType>
<authentication>password-cleartext</authentication>
<username>%EMAILADDRESS%</username>
</incomingServer>
<outgoingServer type="smtp">
<hostname>webmail.workaround.org</hostname>
<port>587</port>
<socketType>STARTTLS</socketType>
<authentication>password-cleartext</authentication>
<username>%EMAILADDRESS%</username>
</outgoingServer>
</emailProvider>
</clientConfig>I suggest putting this file into /var/www/html/autoconfig-mail/config-v1.1.xml and editing your Apache virtual host configuration (/etc/apache2/sites-enabled/webmail.example.org-https.conf) slightly:
Alias /.well-known/autoconfig/mail /var/www/html/autoconfig-mail
Try to load that URL /.well-known/autoconfig/mail/config-v1.1.xml from your domain in your web browser. At least Firefox and Chrome-based browsers validate the XML content automatically and tell you if you made a syntax mistake. No errors? Very good.
Obviously if you want to provide different settings for different domains then you need to create multiple configurations. In most setups the name of the mail server will probably be identical for all hosted domains.
Now next time you set up an account using Thunderbird (or other mail clients that support auto-configuration this way) your users will have a very pleasant quick way to add their email account. Try it out.
Moin Christoph,
Both links to developer.mozilla.org (about the various methods for autoconf and for the XML syntax) are dead.
The links to the ISPDB and the second link about the XML syntax at wiki.mozilla.org are still good.
Greetings
Dennis
P.S.
As always, this is a great tutorial! Thank you very much!
Thanks, Dennis. I’m now linking to archive.org because I couldn’t see where they moved the files to. If anyone finds them please let me know.
That’s an amazing feature! For my servers, Thunderbird always got it wrong and then complained about mismatching certs. Well duh, I could have told you that, Thunderbird – if you’d let me enter the correct data before guessing the wrong one. Well, that should now be a problem of the past. 😉
This link looks like it’s currently working:
https://wiki.mozilla.org/Thunderbird:Autoconfiguration
Perfect, thanks. Added.
Hello Christoph, how can we configure autodiscover on outlook? Seems pretty undocumented, maybe you know something…
I can’t tell for sure. But I assume that Micr0soft maintains their own database of domains for “common” mail service providers.
There’s a lot of Outlook autodiscover XML files available, even php scripts (or other scripting languages) generating Outlook compatible autodiscover.xml on the fly on i.e. Github (Not sure how the policy for posting Github links is – but a search engine can find it pretty fast). This can be integrated in Apache as well as nginx – work’s like a charm as soon one figured out how to debug Outlook stuff which is running under the hood 😀
The autodiscover in Outlook is indeed well documented by Microsoft but the documentation is lacking structure (and is of course Windows based). More or less the format of the required XML file is different: It tells Outlook which server for which protocol and that’s it.
A simple static example of the required XML can be be (Tested with Outlook 2016 & 2019):
email
settings
IMAP
webmail.example.org
143
off
john@example.org
off
on
TLS
on
SMTP
webmail.example.org
587
off
john@example.org
off
on
TLS
on
off
off
Hello Christoph!
Thanks to this great tutorial, I could manage to follow your guide and it works like a charm now 🙂 I learnt a lot from your tutorial.
However 2 small errors occured:
– Today I wanted to send an email to a posteo.org and delivery was refused because: “host mx01.posteo.de[185.67.36.61] refused to talk to
me: 504 5.5.2 : Helo command rejected: need fully-qualified hostname”
After some googling, I added another entry to /etc/hostname:
” webmail.example.com webmail” and changed in /etc/postfix/main.cf the value “myhostname” to the webmail.example.com
-> This resolved the issue and sending to posteo.org succeeded, but I don’t know if this is technically correct?
– Another minor issue was that I could not get the autoconfig to work.
At first I added (as you described above) the vhost webmail.example.com-https.conf with your mentioned alias:
“Alias /.well-known/autoconfig/mail /var/www/html/autoconfig-mail”, but the mail-client (thunderbird 102) failed to discover the settings.
-> But by adding a vhost for “example.com” (only the domain, no subdomain!) with this alias just did the trick. Autoconfig now works perfectly fine 🙂
Just wanted to share in case somebody else happens to come across these issues.
change in /etc/hostname wrong/incomplete,
correct:
add entry ” webmail.example.com webmail”