Autodiscover information for mail clients

General setup

Some mail clients will use a system called "Autodiscover" to figure out which settings to use for the pop/imap/smtp settings.

You can set this up rather easily if you'd like. It basically requires a subdomain and a SRV record. You can add the SRV record for any domain that you'd like to configure Autodiscover for. Using a global SSL certificate in Exim/Dovecot for the hostname would be a good way to ensure clients use the correct value and avoid SSL certificate errors.

Let's assume you're going to have your client with connect to for both IMAP and SMTP.

We'll create a subdomain called to store the XML.

  1. Set up a SRV record in the clientdomain.com DNS zone:
_autodiscover._tcp.clientdomain.com. 3600 IN SRV 10 10 443 autodiscover.hostname.com.
  1. Create the subdomain autodiscover.hostname.com in DA, and add the following code into a file called autodiscover.php :
<?php
//get raw POST data so we can extract the email address
$data = file_get_contents("php://input");
preg_match("/\<EMailAddress\>(.*?)\<\/EMailAddress\>/", $data, $matches);

//set Content-Type
header("Content-Type: application/xml");
echo '<?xml version="1.0" encoding="utf-8" ?>'; ?>

<Autodiscover xmlns="http://schemas.microsoft.com/exchange/autodiscover/responseschema/2006">
   <Response xmlns="http://schemas.microsoft.com/exchange/autodiscover/outlook/responseschema/2006a">
       <Account>
           <AccountType>email</AccountType>
           <Action>settings</Action>
           <Protocol>
               <Type>IMAP</Type>
               <Server>server.hostname.com</Server>
               <Port>993</Port>
               <DomainRequired>off</DomainRequired>
               <LoginName><?php echo $matches[1]; ?></LoginName>
               <SPA>off</SPA>
               <SSL>on</SSL>
               <AuthRequired>on</AuthRequired>
           </Protocol>
           <Protocol>
               <Type>POP3</Type>
               <Server>server.hostname.com</Server>
               <Port>995</Port>
               <DomainRequired>off</DomainRequired>
               <LoginName><?php echo $matches[1]; ?></LoginName>
               <SPA>off</SPA>
               <SSL>on</SSL>
               <AuthRequired>on</AuthRequired>
           </Protocol>
           <Protocol>
               <Type>SMTP</Type>
               <Server>server.hostname.com</Server>
               <Port>587</Port>
               <DomainRequired>off</DomainRequired>
               <LoginName><?php echo $matches[1]; ?></LoginName>
               <SPA>off</SPA>
               <Encryption>TLS</Encryption>
               <AuthRequired>on</AuthRequired>
               <UsePOPAuth>off</UsePOPAuth>
               <SMTPLast>off</SMTPLast>
           </Protocol>
       </Account>
   </Response>
</Autodiscover>
  1. Install an SSL for autodiscover.hostname.com. It can be a commercial SSL or via Let's Encrypt. The SRV record is using port 443 for autodiscover.hostname.com, so make sure you have a valid certificate configured for this subdomain.

If needed, you can set SMTP to use port 465, but you'd have to change the <Encryption> tag's data from TLS to SSL since the protocol is different on 465. Port 587 requires smtp-auth but skips some spam checks and uses STARTTLS to enable SSL. Port 465 is full SSL but clients might have issues sending if their IP/IP range is in an RBL.

  1. Lastly, we'll need to set up an .htaccess file so that any request to the autodiscover.hostname.com subdomain results in the autodiscover.php being called. In the subdomain's DocumentRoot, create the .htaccess with this code:
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} -s [OR]
RewriteCond %{REQUEST_FILENAME} -l [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^.*$ - [NC,L]
RewriteRule ^.*$ autodiscover.php [NC,L]

Thunderbird special

Unlike Microsoft auto-detect, Thunderbird does a direct attempt on

http://autoconfig.clientdomain.com/mail/config-v1.1.xml?emailaddress=user@domain.com

This can be handled by creating a subdomain called "autoconfig", and in the web-area for this subdomain, create a folder called "mail", and inside this "mail" directory, create a file called config-v1.1.xml. A sample path in the File Manager might look like:

/domains/{{clientdomain}}/public_html/autoconfig/mail/config-v1.1.xml

Inside this file, place the code:

<clientConfig version="1.1">
 <emailProvider id="clientdomain.com">
   <domain>clientdomain.com</domain>
   <displayName>%EMAILADDRESS%</displayName>
   <incomingServer type="imap">
     <hostname>mail.clientdomain.com</hostname>
     <port>993</port>
     <socketType>SSL</socketType>
     <username>%EMAILADDRESS%</username>
     <authentication>password-cleartext</authentication>
   </incomingServer>
   <outgoingServer type="smtp">
     <hostname>smtp.clientdomain.com</hostname>
     <port>587</port>
     <socketType>STARTTLS</socketType>
     <username>%EMAILADDRESS%</username>
     <authentication>password-cleartext</authentication>
   </outgoingServer>
 </emailProvider>
</clientConfig>

Configure DNS for autodiscover

Add DNS SRV record by default for the new domains

cd /usr/local/directadmin/data/templates/custom/
cp ../dns_srv.conf .

Open the dns_srv.conf file and add:

_autodiscover._tcp.|DOMAIN|.=10 10 443 autodiscover.hostname.com.

Add DNS record for the existing domains (a temporary customisation!)

This method uses the default named.conf template to read current contents and simply append a custom line at the end of a dns zone.

cd /usr/local/directadmin/data/templates/custom/
cp ../named.db .

Open named.db file and on the bottom of a file add:

_autodiscover._tcp.|DOMAIN|. 3600 IN SRV 10 10 443 autodiscover.hostname.com.

Then rewrite zones for all domains:

echo "action=rewrite&value=named" >> /usr/local/directadmin/data/task.queue
/usr/local/directadmin/dataskq d80

Now, remove the custom named.conf file

rm -fv /usr/local/directadmin/data/templates/custom/named.conf

Do NOT forget to remove this custom named.conf file from the custom dir. Each time DirectAdmin reads the user's DNS zone, the existing SRV record gets read under the |SRV| section of the template, so your customisation gets appended to the same zone again.

Last Updated: