What Is Email Autoconfig?

Email autoconfig is a feature that allows mail clients — such as Mozilla Thunderbird, Microsoft Outlook, and Apple Mail — to automatically discover your email server's incoming and outgoing settings when a user enters their email address. Instead of requiring users to manually input IMAP, POP3, and SMTP details, the mail client fetches a configuration file from a known URL on your domain.

Setting this up correctly saves your users time, reduces support tickets, and ensures everyone connects to the right server with the right security settings.

How Autoconfig Works

When a mail client attempts to configure a new account for user@yourdomain.com, it looks for a configuration file in a predictable location on your domain. Thunderbird, for example, checks for a file at:

  • https://autoconfig.yourdomain.com/mail/config-v1.1.xml
  • https://yourdomain.com/.well-known/autoconfig/mail/config-v1.1.xml

Outlook uses a slightly different mechanism called Autodiscover, which looks for an XML file at https://autodiscover.yourdomain.com/autodiscover/autodiscover.xml.

Step 1: Create the Autoconfig XML File

Below is a standard Thunderbird-compatible autoconfig XML file. Replace the placeholder values with your actual server details:

<?xml version="1.0" encoding="UTF-8"?>
<clientConfig version="1.1">
  <emailProvider id="yourdomain.com">
    <domain>yourdomain.com</domain>
    <displayName>Your Mail Service</displayName>
    <incomingServer type="imap">
      <hostname>mail.yourdomain.com</hostname>
      <port>993</port>
      <socketType>SSL</socketType>
      <authentication>password-cleartext</authentication>
      <username>%EMAILADDRESS%</username>
    </incomingServer>
    <outgoingServer type="smtp">
      <hostname>mail.yourdomain.com</hostname>
      <port>587</port>
      <socketType>STARTTLS</socketType>
      <authentication>password-cleartext</authentication>
      <username>%EMAILADDRESS%</username>
    </outgoingServer>
  </emailProvider>
</clientConfig>

Step 2: Host the File on Your Server

Upload the XML file to one of the expected locations. The most reliable approach is to create a subdomain autoconfig.yourdomain.com and point it to a directory on your web server that serves the file. Make sure the web server returns the correct MIME type: text/xml or application/xml.

Step 3: Set Up the Autodiscover File for Outlook

Create a separate XML file for Outlook's Autodiscover protocol. The structure differs slightly and uses Microsoft's XML namespace. Place it at https://autodiscover.yourdomain.com/autodiscover/autodiscover.xml and ensure it responds to HTTP POST requests, as Outlook sends a POST when probing the endpoint.

Step 4: Add DNS Records

For autoconfig to work, you need DNS entries pointing to your server:

  • An A record for autoconfig.yourdomain.com pointing to your server IP.
  • An A record (or CNAME) for autodiscover.yourdomain.com pointing to the same location.
  • Optionally, an SRV record: _autodiscover._tcp.yourdomain.com for broader client compatibility.

Step 5: Test Your Configuration

Use these tools to verify everything is working:

  1. Thunderbird — simply create a new account with your email address and watch it auto-detect settings.
  2. Microsoft Remote Connectivity Analyzer (testconnectivity.microsoft.com) — tests Autodiscover endpoints.
  3. MXToolbox — check that your DNS records are correctly propagated.

Common Issues to Watch Out For

  • SSL certificate errors — your autoconfig subdomain must have a valid SSL certificate.
  • CORS headers — some clients require the server to return permissive CORS headers on the config file.
  • Incorrect MIME type — serving the XML as plain text can cause clients to reject it.

Taking the time to configure email autoconfig properly is a one-time investment that pays dividends every time a new user sets up their mail client on your domain.