Autodiscover
You’ll want this if you have a lot of clients. There is an RFC but most fail to implement it. The conventional solution is to serve up the config from a web site. It’s best to create a dedicated vhost as each client has a slightly different approach.
Web AutoConfig
DNS Name
In your DNS or provider, create two entries; one for Thunderbird and one for Outlook. These should be CNAME records pointing to your web server.
- autoconfig
- autodiscover
VHOST
On your web server, create a website to handle these. If you’re using a wildcard and handle setup (and you should be), a config block would look like
@mail-discovery host autoconfig.your.org autodiscover.your.org
handle @mail-discovery {
encode
root * /var/www/autoconfig.your.org
file_server
}
Files
Create the directory and file using this template. This is set up with the current standard of implicit SSL.
Thunderbird
mkdir -p /var/www/autoconfig.your.org/mail
vi /var/www/autoconfig.your.org/mail/config-v1.1.xml
<?xml version="1.0" encoding="UTF-8"?>
<clientConfig version="1.1">
<emailProvider id="your.org">
<domain>your.org</domain>
<displayName>Your Mail</displayName>
<displayShortName>Your</displayShortName>
<!-- Incoming Mail Server (IMAP) -->
<incomingServer type="imap">
<hostname>mail.your.org</hostname>
<port>993</port>
<socketType>SSL</socketType>
<authentication>password-cleartext</authentication>
<username>%EMAILADDRESS%</username>
</incomingServer>
<!-- Outgoing Mail Server (SMTP) -->
<outgoingServer type="smtp">
<hostname>mail.your.org</hostname>
<port>465</port>
<socketType>SSL</socketType>
<authentication>password-cleartext</authentication>
<username>%EMAILADDRESS%</username>
</outgoingServer>
</emailProvider>
</clientConfig>
Outlook
mkdir -p /var/www/autoconfig.your.org/autodiscover
vi /var/www/autoconfig.your.org/autodiscover/autodiscover.xml
<?xml version="1.0" encoding="utf-8"?>
<Autodiscover xmlns="http://microsoft.com">
<Response xmlns="http://microsoft.com">
<Account>
<AccountType>email</AccountType>
<Action>settings</Action>
<Protocol>
<Type>IMAP</Type>
<Server>mail.your.org</Server>
<Port>993</Port>
<SSL>on</SSL>
<AuthRequired>on</AuthRequired>
<SPA>off</SPA>
<LoginName>%EmailAddress%</LoginName>
</Protocol>
<Protocol>
<Type>SMTP</Type>
<Server>mail.your.org</Server>
<Port>465</Port>
<SSL>on</SSL>
<AuthRequired>on</AuthRequired>
<SPA>off</SPA>
<LoginName>%EmailAddress%</LoginName>
</Protocol>
</Account>
</Response>
</Autodiscover>
IOS
The mail app won’t configure itself directly, but you can visit the URL in Safari and it should prompt you. I’ve not tested this so take with a grain of salt. This would be http://autodiscover.your.org/apple/gattis.mobileconfig.
Update your Caddy config block with the content type. (not tested to see if actually needed)
@mail-discovery host autoconfig.your.org autodiscover.your.org
handle @mail-discovery {
header *.xml Content-Type "text/xml; charset=utf-8"
header *.mobileconfig Content-Type "application/x-apple-aspen-config; charset=utf-8"
encode
root * /var/www/autoconfig.your.org
file_server
}
```bash
mkdir -p /var/www/autoconfig.your.org/apple
vi /var/www/autoconfig.your.org/apple/your.mobileconfig
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://apple.com">
<plist version="1.0">
<dict>
<key>PayloadContent</key>
<array>
<dict>
<key>PayloadDescription</key>
<string>Configures mail settings for your.org</string>
<key>PayloadDisplayName</key>
<string>Your Mail Account</string>
<key>PayloadIdentifier</key>
<string>org.your.mail</string>
<key>PayloadType</key>
<string>com.apple.mail.managed</string>
<key>PayloadUUID</key>
<string>6A2B84D2-E123-4567-89AB-CDEF01234567</string>
<key>PayloadVersion</key>
<integer>1</integer>
<key>EmailAccountType</key>
<string>EmailTypeIMAP</string>
<key>EmailAccountDescription</key>
<string>Your Mail</string>
<key>IncomingMailServerHostName</key>
<string>mail.your.org</string>
<key>IncomingMailServerPortNumber</key>
<integer>993</integer>
<key>IncomingMailServerUseSSL</key>
<true/>
<key>IncomingMailServerUsername</key>
<string></string> <!-- Left blank so user inputs their specific prefix -->
<key>OutgoingMailServerHostName</key>
<string>mail.your.org</string>
<key>OutgoingMailServerPortNumber</key>
<integer>465</integer>
<key>OutgoingMailServerUseSSL</key>
<true/>
<key>OutgoingMailServerUsername</key>
<string></string>
</dict>
</array>
<key>PayloadDisplayName</key>
<string>Your Email Configuration</string>
<key>PayloadIdentifier</key>
<string>org.your.profile</string>
<key>PayloadRemovalDisallowed</key>
<false/>
<key>PayloadType</key>
<string>Configuration</string>
<key>PayloadUUID</key>
<string>1F4E92A1-ABCD-EF01-2345-67890ABCDEF1</string>
<key>PayloadVersion</key>
<integer>1</integer>
</dict>
</plist>
DNS SRV
And of course, the best thing about standards are that there are so many to pick from. So I suppose we can create entries as per the RFC.
# Secure IMAP (Implicit TLS - Port 993)
_imaps._tcp.gattis.org. SRV 10 10 993 mail.your.org.
# Secure SMTP Submission (STARTTLS - Port 587)
_submission._tcp.gattis.org. SRV 10 10 587 mail.your.org.
Note
It’s traditional to match server names to protocols and we would have used “imap.your.org” and “smtp.your.org”. But using ‘mail’ is popular now and it simplifies setup at several levels.
Thunderbird will try to guess at your server names, attempting to connect to smtp.your.org for example. But many Postfix configurations have spam prevention that interfere.
Sources
https://cweiske.de/tagebuch/claws-mail-autoconfig.htm
https://www.hardill.me.uk/wordpress/2021/01/24/email-autoconfiguration/
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.