Set up Autodiscover for SmarterMail

This article applies to recent versions of SmarterMail. View articles for SmarterMail 16.x and earlier.
Autodiscover is a service that allows email clients to automatically determine a user’s mail server address and port from that user’s email address and password alone. This greatly simplifies a user’s setup process when attempting to connect SmarterMail to a desktop client, like Outlook and Windows Mail, as well as mobile clients on their iPhone, iPad, Android, Windows Phone and other mobile devices.
 
Autodiscover is supported by POP, IMAP, SMTP In, MAPI/EWS and EAS. However, not all email clients handle Autodiscover in the same way. For example, when connecting SmarterMail to mobile devices, only EAS connections will use Autodiscover. Outlook 2007 and above will return only IMAP connections. The Windows Mail client will return EAS, and while Thunderbird does not support Autodiscover at all, it will make the best effort to connect to any mail server. Because each client handles Autodiscover differently, it’s important to review the support documentation of your users’ preferred email client(s) to learn the connection type that’s best suited.
 
NOTE: Utilizing Autodiscover with MAPI/EWS or EAS requires encryption over SSL or TLS. Therefore, port 443 MUST be available and not blocked by a firewall. For instructions on this configuration, please see Configure SSL/TLS to Secure SmarterMail.
 
To configure Autodiscover for a SmarterMail domain, a SmarterMail Administrator must perform the following:
 
  • Configure the domain’s Autodiscover settings within SmarterMail
  • Create an A Record for the domain in the DNS configuration
  • Create an SRV Record for the domain in the DNS configuration
  • Create an IIS binding for Autodiscover on the SmarterMail server
  • Configure an IIS rewrite rule*
*This is only necessary if your SmarterMail site starts with a subdomain, and a website on a different server uses that same domain name.
 

Configure the Domain’s Autodiscover Settings within SmarterMail

Follow these steps to adjust the protocols enabled for Autodiscover and the ports on which they listen:
 
  1. Log in to SmarterMail as a system administrator. 
  2. Click on the Manage icon. In the Domains section, click on a domain to open its configuration settings. 
  3. On the Options card, ensure the correct Hostname is entered. The hostname is the URL that will be returned when users attempt to connect to their email client. The most common hostname for a mail URL is “mail.yourdomain.com”. 
  4. On the Autodiscover card, adjust the configuration options as needed. Here, you can enable or disable specific protocols from returning Autodiscover results. When a protocol is enabled for Autodiscover, clicking on that protocol’s settings cog will open a window where the encryption type and port can be adjusted. (EAS and EWS require encryption over SSL/TLS and this configuration cannot be modified.) NOTE: If a user has POP disabled for their account, their POP Autodiscover request will not be fulfilled, even if POP is enabled for Autodiscover. This applies to all protocols in their account's Service Access settings.
Modifying the Default XML Response (optional)
NOTE: The Override Desktop XML and Override Mobile XML options should NOT be modified without advanced knowledge of the XML responses used with Autodiscover. Adjusting the custom XML incorrectly can result in invalid responses returned meaning users will be unable to connect to their email client(s).
 
Administrators with advanced Autodiscover knowledge can override the default XML response that is sent from the domain when Autodiscover is requested. There are two types of Autodiscover responses that can be modified: Mobile XML and Desktop XML. The mobile XML response is strictly used with Exchange ActiveSync. The desktop XML response is used with everything else, including IMAP, POP, SMTP In and Exchange Web Services.
 
Follow these steps to override the desktop or mobile XML response sent by SmarterMail:
 
  1. Enable Override Desktop XML or Override Mobile XML
  2. Click on the textbox that appears for Custom Desktop XML or Custom Mobile XML.
  3. In the textbox window that appears, clicking on Generate will show the XML response that SmarterMail would normally send on an Autodiscover request. You can generate this response to make adjustments as needed, or simply enter the XML response you would like to use. 
  4. NOTE: If you turn on an override but never save any custom XML, SmarterMail will use the default protocol settings. However, if the override is turned on, ANY text you save to the Custom XML area will be used for the Autodiscover response. If you save custom text, then later remove that text and save a blank entry, Autodiscover will send a blank response. Therefore, it is imperative that you only enable the override and enter custom Autodiscover XML if you are absolutely sure what you're using is correct.
Other items to note:
 
  • You can adjust the XML reply as needed. However, don’t remove or modify these variables:
    • %EmailAddress%
    • %Base64EmailAddress%
    • %DisplayName%
    • %LegacyDN%
  • The above variables are used to identify the user making the Autodiscover request. (%Base64EmailAddress% is used in SmarterMail version 17.x and higher.)
  • Any changes made to the XML response should be within the RFC guidelines, though this is not validated by SmarterMail.
 

Create an A Record for the Domain in the DNS configuration

For Autodiscover to work, each domain needs an A Record for "autodiscover.yourdomain.com" that points to the IP address of your mail server. For example, for SmarterTools, we set up an A Record for "autodiscover.smartertools.com" that points to the IP address of our mail server (mail.smartertools.com). In our DNS, the line in our zone file for this A Record looks like this:
autodiscover IN A 69.71.61.105
There are many ways to manage DNS for a domain, as well as many DNS services that can be used, so providing step-by-step instructions on this configuration is difficult. However, adding a record should be fairly straightforward. If you have questions, contact your IT professional, hosting provider or DNS provider for assistance.
 

Create an SRV Record for the Domain in the DNS configuration

Next, you'll want to create an SRV record for your domain. This SRV Record will return the available domain and service (SMTP, POP or IMAP) to the email client requesting Autodiscovery. Technically, setting up an SRV Record is an optional step; however, it is highly recommended as a backup to ensure Autodiscover works properly.
 
The SRV Record that is created should be in the following format and return the root URL of your email server:
_autodiscover._tcp.(your domain)
There are many ways to manage DNS for a domain, as well as many DNS services that can be used, so providing step-by-step instructions on this configuration is difficult. Please check with your IT professional, hosting provider or DNS provider for instructions on configuring an SRV Record for your environment. The following example details the SRV configuration for SmarterTools:
 
Domain: smartertools.com
Service: _Autodiscover
Protocol: _tcp
Priority: 0
Weight: 0
Port: 443
 
Verify the SRV via NSLookup (optional)
Follow these settings to verify that you have set up the SRV Record correctly:
 
  1. On a Windows machine, open the Command Prompt and do the following:
  2. Type NSLOOKUP and press ENTER.
  3. Type set type=srv and press ENTER.
  4. Type _autodiscover._tcp.yourdomain.com, where "yourdomain.com" is the name of your domain, and press ENTER.
In return, you should get something similar to what's shown below, with the IP addresses and server URLs matching what you have set up for your mail server. If your results differ or no results are returned, please review your DNS configuration. It's possible the issue is caused due to DNS caching or replication.
Server: UnKnown Address: 127.0.0.1 Non-authoritative answer: _autodiscover._tcp.your-domain.com SRV service location: priority = 0 weight = 0 port = 443 svr hostname = mail.your-domain.com mail.your-domain.com internet address = 127.0.0.2
 

Create an IIS binding (Host Header) for Autodiscover on the SmarterMail Server

In IIS, a host header for Autodiscover should be added to your SmarterMail website that points your Autodiscover A Record to your SmarterMail installation. For example, for SmarterTools, we have an IIS binding that binds port 80 and 443 to "autodiscover.smartertools.com." This is added in addition to the IIS binding for "mail.smartertools.com", which is the URL used for setting up email clients and accessing the web interface.
 
If your SmarterMail installation is on a * binding and listens for any host header, you'll just need to add the necessary DNS records. However, if host headers are used for each domain, a host header must be added for each domain for both Autodiscover and webmail.
 
To learn how to configure a host header in IIS, please review Microsoft’s documentation. After the IIS binding has been configured, perform an IIS reset. 

Configure an IIS rewrite rule

NOTE: This step is only necessary if your environment matches what's described below. If you do not have a company website that uses the same domain as your mail server subdomain, you may skip this step.

If your SmarterMail site starts with a subdomain (such as mail.yourdomain.com), and a website on a different server uses that same domain name (ex: yourdomain.com), an IIS rewrite is required in order to help the Autodiscover process find the correct server. For example, here at SmarterTools, we have a server that hosts our company website which points to smartertools.com. On a different server, we host our SmarterMail installation which points to mail.smartertools.com. SmarterMail users are configured with email addresses in the format user@smartertools.com.

This issue we've found is that some Autodiscover clients will take the user's email address and do an Autodiscover lookup based on the domain, smartertools.com. This lookup will send the Autodiscover request to the server that hosts the company website, not the server that hosts the SmarterMail installation. Adding an IIS rewrite rule on the server that hosts the company website helps to prevent this issue. 

To configure the URL Rewrite, you can either: Create a Rewrite Rule within IIS OR add the rewrite parameters to the site's web.config file. 

Create a URL Rewrite within IIS
Follow these steps if you'd like to add the rewrite rule by creating a URL Rewrite within IIS: 
(Note: These instructions are for IIS 10. Steps may vary when using a different version of IIS.)
  1. Log in to the server that hosts your company website. 
  2. Install the extension, URL Rewrite Module 2.0. For assistance and more information, see Using URL Rewrite Module 2.0
  3. After the URL Rewrite Module has been installed, open Internet Information Services (IIS) Manager.
  4. In the navigation pane, expand the server name folder and Sites folder. Click on the site that's used for your company website.
  5. In the preview pane that lists the site features, under the IIS section, double-click on URL Rewrite.
  6. In the righthand Actions pane, click on Add Rules....
  7. Under the Inbound rules section, click on Blank rule.
  8. The Edit Inbound Rules window should be modified with the following parameters:
    • Name: Redirect rule1 for /autodiscover/autodiscover.xml
    • Requested URL: Matches the Pattern
    • Using: Regular Expressions
    • Pattern: .*
    • Ignore case: Enabled
    • Conditions
      • Logical Grouping: Match All
      • Click Addto create a new condition:
        • Condition Input: {/autodiscover/autodiscover.xml:{REQUEST_URI}}
        • Check if input string: Matches the Pattern
        • Pattern: (.+)
        • Click OK to submit the new condition. 
      • Track capture groups across conditions: Disabled
    • Server Variables: None
    • Action
      • Action Type: Redirect
      • Action Properties
        • Redirect URL: {C:1}
        • Append query string: Disabled
        • Redirect type: Permanent (301)
  9. In the righthand pane, click Apply to save the Inbound Rule. 
  10. After the Inbound Rule has been configured, perform an IIS reset.

Add the rewrite parameters to the web.config file
Follow these steps if you'd like to add the rewrite rule by modifying the company website's web.config file: 

  1. Log in to the server that hosts the company website.
  2. Navigate to the company website's web.config file. (The location of the web.config file can vary but is typically found under your IIS directory.)
  3. Edit the web.config file (using a text editor or, ideally, something like SublimeText that preserves formatting) and add the following parameters to the system.webServer sections. Don't forget to replace the URL, https://mail.DOMAIN.com/autodiscover/autodiscover.xml, with your own mail server domain.

    <system.webServer>
      <rewrite>
            <rewriteMaps>
                <rewriteMap name="/autodiscover/autodiscover.xml">
                    <add key="/autodiscover/autodiscover.xml" value="https://mail.DOMAIN.com/autodiscover/autodiscover.xml" />
                 </rewriteMap>
            </rewriteMaps>
                <rules>
                    <rule name="Redirect rule1 for /autodiscover/autodiscover.xml">
                        <match url=".*" />
                        <conditions>
                            <add input="{/autodiscover/autodiscover.xml:{REQUEST_URI}}" pattern="(.+)" />
                        </conditions>
                        <action type="Redirect" url="{C:1}" appendQueryString="false" />
                    </rule>
                </rules>
            </rewrite>
        </system.webServer>
  4. After saving the changes to the web.config file, perform an IIS reset.

Once all of these steps have been configured, users can sync their SmarterMail account to any email client that supports Autodiscover using only their email address and password. SmarterMail will take care of the rest!

TROUBLESHOOTING
Here are a few things to test to ensure things are set up correctly. If one or more of these fail, you will need to fix those issues before troubleshooting further.

  1. In a browser, navigate to https://mail.your-domain.com. This should resolve successfully to the SmarterMail web interface and without SSL or other errors. 
  2. Navigate to https://autodiscover.your-domain.com. This should resolve successfully to the SmarterMail web interface and without SSL or other errors. 
  3. Navigate to https://your-domain.com/autodiscover/autodiscover.xml. These requests should be redirected to https://mail.your-domain.com/autodiscover/autodiscover.xml so that SmarterMail handles the request. 
  4. Check DNS for your-domain.com. It should contain an SRV record that references mail.your-domain.com on port 443 to avoid certificate errors due to hostname mismatches and the like. 
 
 
Learn more about SmarterMail's enterprise email features and benefits.

Feedback

Creating an A Record cause Outlook to prompt SSL certificate not trusted. Unless you have a wildcard or SAN SSL certificate. If you are using cheap single domain name SSL certificate, just create the DNS SRV record.
BIS Techies (Rebecca and Family) (4/8/2014 at 7:15 PM)
How to add these to cPanel Advanced DNS running its own autodiscover. We are running on a Sub-domain.
Chinmay Khandekar (12/16/2014 at 6:28 PM)
Hi Chinmay, That is actually something you'll need to contact cPanel about.
Andrea Free (12/17/2014 at 8:47 AM)
I have set it up like this, so customers kan connect to the smartermail server using the ssl cert of the mailserver.

Non-authoritative answer:
_autodiscover._tcp.client-domain.com SRV service location:
priority = 0
weight = 0
port = 443
svr hostname = mail.hosting-isp-domain.com

mail.hosting-isp-domain.com internet address = <public IP nr>

Richard Frank (4/6/2016 at 3:43 AM)
SNI must be enabled when adding the new binding in order to select a different SSL certificate for the autodiscover.domain.ext. Otherwise, it will use the same SSL certificate as your webmail, which will throw up warnings when trying to autodiscover.
Stephen Roesch (11/2/2016 at 7:06 AM)
So, if you need to add autodiscover.x.x for port 80 and 443 on the existing SmarterMail server's IIS, it throws up the "Binding already being used by a product other than IIS”. I added a second IP to the site and bound autodiscover to those, but it still won't resolve for clients. ?
Andrew Lupton (1/9/2017 at 1:05 PM)
Hi Andrew! Thank you for reaching out. I would encourage you to review this issue with our Support Department through the use of an Email or Phone Ticket. Please keep in mind that if the issue is determined to be caused by a bug in the software, your ticket / ticket costs would be refunded.
Andrea Free (1/18/2017 at 4:12 PM)
This and other documentations don't explain much about to use one or more IP addresses for one smarter mail instance. Can you (SmarterTools Support Team) please add a help Topic and explain the difference between one or multiple IP addresses and how to enable SSL/TSL support using Multi Domain certificate or single domain certificate. I guess most People get confused about what is possible with each different use case. Regards Roger Ineichen
Roger Ineichen (8/26/2017 at 5:34 PM)
Hi Roger. Sorry about the long delay in a reply. Our article for configuring SmarterMail with SSL/TLS was modified in March to include details about utilizing a Unified Communications Certificate (UCC) for securing multiple domains.

Configure SSL/TLS to Secure SmarterMail: https://portal.smartertools.com/kb/a2671/configure-ssl-tls-to-secure-smartermail.aspx

Our blog post, Securing SmarterMail With Let's Encrypt, may help as well:
https://www.smartertools.com/blog/2017/08/14-secure-smartermail-with-lets-encrypt

Andrea Free (7/30/2018 at 2:36 PM)
The documentation for setting up ActiveSync is extremely poor, especially since ActiveSync is a paid add-on, the resources are not good enough! I am stuck and have tried almost everything to get this working. Try to follow this article exactly and see if it ends up working, some parts are not explained...
Adam (7/27/2018 at 8:14 PM)
Hi Quillo Hosting. I've reached out via email to gather some more information about the trouble you're having.
Andrea Free (7/30/2018 at 2:33 PM)
What about IOS? And Thunderbird?

It would be nice if something like automx.org was build in to Smartermail.

automx makes setting up a mail account easy. All your users need to provide is real name, mail address and password. Their mail client and automx will safely handle the rest.

Frank Jensen (1/26/2019 at 4:45 AM)
Hi Frank. Thanks for the suggestion! I'll pass it onto the development team. For iOS and Thunderbird... Each client will handle Autodiscover requests in their own way. From my understanding, Thunderbird does not support Autodiscover but will make the best effort to connect to the mail server. iOS devices will attempt to return the data over the protocol used - either IMAP, POP and ActiveSync or Exchange Web Services.
Andrea Free (1/28/2019 at 10:36 AM)
Thunderbird actually uses four methods to figure out IMAP settings, including using their own "ISP-DB", and having a "Configuration Server at ISP". Looks like the Configuration Server is a bit complicated, as it requires you host email at your customer's domain name, which you may or may not have access to. There's also a way to add something to your customer's DNS that points the autoconfig to one URL: autoconfig.[hosting-company].com in conjunction with the ISP-DB. We are going to give this a try, as I typically suggest Thunderbird over Outlook or Windows Mail (shudder).

https://developer.mozilla.org/en-US/docs/Mozilla/Thunderbird/Autoconfiguration

Michael Muller (12/10/2019 at 9:20 AM)
I believe your example for "Create a URL Rewrite within IIS" is missing information?? It does not generate the same content as the manual entry in the web.config. For example, where is it specified to redirect to the mail.domain.com....? {C:1} is specified in the IIS version of this. I tried the IIS version first and it shut down my site, the manual version worked.
Neal Culiner (5/27/2019 at 9:09 AM)
Thanks, Neal. I'll get someone to review this and, if changes are required, we'll update the KB.
Derek Curtis (5/28/2019 at 7:51 AM)
Hi, Can someone provide a .htaccess file as well? You're only providing the web.config file assuming web sites are all Microsoft IIS hosted, but most of the internet is serving sites from Linux....so please provide a working .htaccess rule for autodiscovery to still work...thanks!
Adam (6/11/2020 at 7:09 PM)
Hi, Adam

SmarterMail needs to be hosted on a Windows Server machine. As Autodiscover is essentially just IIS bindings for SmarterMail and DNS modifications, I'm not entirely sure why you'd need a .htaccess example?

Derek Curtis (6/13/2020 at 8:58 AM)
Hello Derek, It is very good possible that the company website is hosted on a linux based platform.
"This lookup will send the Autodiscover request to the server that hosts the company website, not the server that hosts the SmarterMail installation. Adding an IIS rewrite rule on the server that hosts the company website helps to prevent this issue. "

Richard Frank (8/31/2020 at 8:33 AM)
Two things need to fix in this article.

1. The step-by-step IIS instructions is missing instructions for adding the rewriteMap that is included in the web.config file; without it the rewrite doesn't work.
...
<rewriteMaps>
<rewriteMap name="/autodiscover/autodiscover.xml">
<add key="/autodiscover/autodiscover.xml" value="https://mail.DOMAIN.com/autodiscover/autodiscover.xml" />
</rewriteMap>
</rewriteMaps>
...

2. You should only provide the Rewrite and rewriteMap code in the web.config file, other code has been included (see below) that doesn't pertain to URL Rewrite. Someone might add it to their server configuration causing unnecessary grief.
...
<urlCompression doDynamicCompression="true" doStaticCompression="true" />
<handlers>
<add name="HtmlFileHandler" path="*.html" verb="GET" type="System.Web.StaticFileHandler" preCondition="integratedMode" />
</handlers>
<httpErrors>
<remove statusCode="404" subStatusCode="-1" />
<error statusCode="404" prefixLanguageFilePath="" path="/Home/NotFound" responseMode="ExecuteURL" />
<remove statusCode="500" subStatusCode="-1" />
<error statusCode="500" prefixLanguageFilePath="" path="/Home/Error" responseMode="ExecuteURL" />
</httpErrors>
<staticContent>
<remove fileExtension=".woff2" />
<mimeMap fileExtension=".woff2" mimeType="application/font-woff2" />
</staticContent>
...

Jerry Bucci (7/13/2020 at 8:38 PM)
So insert 1. into the web.config and not use .2 at all?

Where do I insert 1. in the web.config?

Heimir Eidskrem (7/21/2020 at 12:11 PM)