Mail Client Auto-Configuration

Posted on 14 2026

When a user adds an email account to a mail client, the client tries to discover the correct server settings automatically before asking the user to enter anything. Mozilla’s autoconfig protocol and Microsoft’s Autodiscover protocol are the two mechanisms most clients support. Configure both and new mail clients configure themselves from an email address and password alone, with no manual server entry required.

This is worth doing even for a personal mail server with one or two users. Adding a new device, a new phone, or a new desktop, takes thirty seconds rather than looking up server names and port numbers.

This series uses Evolution as the primary mail client. Evolution supports Mozilla’s autoconfig format. KMail also supports it. Thunderbird uses it natively. iOS and Android mail clients support Microsoft Autodiscover. Configuring both covers all the common cases.

How autoconfig works

The client tries to access the following URLs in the preferred order:

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

If successful, the XML data received is used as configuration hints.

For Microsoft clients, these clients first look up a DNS service record to locate any available web server who might have configuration data in store for the user’s mail domain.

The autoconfig service is served by nginx from the web container or a dedicated autoconfig container. The XML files are static: no dynamic generation is needed.

DNS records

Add DNS records to make the autoconfig subdomain resolvable. These go in your public DNS zone for yourdomain.net:

Mozilla autoconfig

; Autoconfig for Mozilla clients (Evolution, Thunderbird, KMail)
autoconfig    IN    A       your.wan.ip.address
autoconfig    IN    AAAA    your::ipv6::address

Microsoft Autodiscover

; Autodiscover for Microsoft and Apple clients (Outlook, iOS Mail)
autodiscover  IN    A       your.wan.ip.address
autodiscover  IN    AAAA    your::ipv6::address

; SRV record for Autodiscover v1
_autodiscover._tcp    IN    SRV    10 10 443 autodiscover.yourdomain.net.

If autoconfig.yourdomain.net and autodiscover.yourdomain.net resolve to the same server as mail.yourdomain.net, CNAME records pointing at mail.yourdomain.net are cleaner than duplicate A records:

autoconfig      IN    CNAME    mail.yourdomain.net.
autodiscover    IN    CNAME    mail.yourdomain.net.

TLS certificates

Both autoconfig.yourdomain.net and autodiscover.yourdomain.net must have valid TLS certificates since clients connect via HTTPS. Add them to the Let’s Encrypt certificate request:

certbot certonly --nginx \
    -d mail.yourdomain.net \
    -d autoconfig.yourdomain.net \
    -d autodiscover.yourdomain.net

Or add them to the existing nginx TLS configuration covering the mail server.

nginx configuration

Create the nginx configuration to serve the autoconfig XML files. This can be added to the existing mail server nginx configuration or served from the web container.

Create /etc/nginx/sites-available/autoconfig:

# Mozilla Autoconfig
server {
    listen 80;
    server_name autoconfig.yourdomain.net;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name autoconfig.yourdomain.net;

    ssl_certificate /etc/letsencrypt/live/mail.yourdomain.net/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mail.yourdomain.net/privkey.pem;

    root /var/www/autoconfig;
    index index.html;

    # Mozilla autoconfig path
    location /mail/config-v1.1.xml {
        default_type application/xml;
        add_header Content-Type "application/xml; charset=utf-8";
    }

    # Well-known path (fallback)
    location /.well-known/autoconfig/mail/config-v1.1.xml {
        alias /var/www/autoconfig/mail/config-v1.1.xml;
        default_type application/xml;
        add_header Content-Type "application/xml; charset=utf-8";
    }
}

# Microsoft Autodiscover
server {
    listen 80;
    server_name autodiscover.yourdomain.net;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name autodiscover.yourdomain.net;

    ssl_certificate /etc/letsencrypt/live/mail.yourdomain.net/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mail.yourdomain.net/privkey.pem;

    root /var/www/autoconfig;

    location /autodiscover/autodiscover.xml {
        default_type application/xml;
        add_header Content-Type "application/xml; charset=utf-8";
    }

    # Autodiscover v2 (used by newer Outlook versions)
    location /autodiscover/autodiscover.json {
        default_type application/json;
        add_header Content-Type "application/json; charset=utf-8";
    }
}

Create the document root:

sudo mkdir -p /var/www/autoconfig/mail
sudo mkdir -p /var/www/autoconfig/autodiscover

Enable the site:

sudo ln -s /etc/nginx/sites-available/autoconfig /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Mozilla autoconfig XML

Create /var/www/autoconfig/mail/config-v1.1.xml:

<?xml version="1.0" encoding="UTF-8"?>
<clientConfig version="1.1">
    <emailProvider id="yourdomain.net">

        <!-- Domains covered by this configuration -->
        <domain>yourdomain.net</domain>

        <displayName>Your Mail Server</displayName>
        <displayShortName>yourdomain.net</displayShortName>

        <!-- Incoming mail: IMAP over SSL -->
        <incomingServer type="imap">
            <hostname>mail.yourdomain.net</hostname>
            <port>993</port>
            <socketType>SSL</socketType>
            <authentication>plain</authentication>
            <username>%EMAILADDRESS%</username>
        </incomingServer>

        <!-- Outgoing mail: SMTP submission with STARTTLS -->
        <outgoingServer type="smtp">
            <hostname>mail.yourdomain.net</hostname>
            <port>587</port>
            <socketType>STARTTLS</socketType>
            <authentication>plain</authentication>
            <username>%EMAILADDRESS%</username>
        </outgoingServer>

        <!-- Documentation link (optional) -->
        <documentation url="https://yourdomain.net/mail/help">
            <descr lang="en">Mail server configuration</descr>
        </documentation>

    </emailProvider>
</clientConfig>

The %EMAILADDRESS% placeholder is replaced by the client with the actual email address being configured.

Microsoft Autodiscover XML

Create /var/www/autoconfig/autodiscover/autodiscover.xml:

<?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>mail.yourdomain.net</Server>
                <Port>993</Port>
                <LoginName/>
                <DomainRequired>off</DomainRequired>
                <SPA>off</SPA>
                <SSL>on</SSL>
                <AuthRequired>on</AuthRequired>
            </Protocol>
            <Protocol>
                <Type>SMTP</Type>
                <Server>mail.yourdomain.net</Server>
                <Port>587</Port>
                <LoginName/>
                <DomainRequired>off</DomainRequired>
                <SPA>off</SPA>
                <SSL>STARTTLS</SSL>
                <AuthRequired>on</AuthRequired>
            </Protocol>
        </Account>
    </Response>
</Autodiscover>

Autodiscover v2 JSON (modern Outlook)

Newer versions of Outlook use a JSON-based Autodiscover v2 format. Create /var/www/autoconfig/autodiscover/autodiscover.json:

{
    "Protocol": "IMAP",
    "Url": "https://mail.yourdomain.net"
}

This minimal JSON response tells Outlook where to find the IMAP server. Outlook then connects to the IMAP server and discovers the remaining settings from its IMAP capability response.

Well-known path

Some clients use the .well-known path on the root domain rather than the autoconfig subdomain. Create a symlink or copy the XML file to the well-known location on the main domain’s web root:

sudo mkdir -p /var/www/yourdomain.net/.well-known/autoconfig/mail
sudo ln -s /var/www/autoconfig/mail/config-v1.1.xml \
    /var/www/yourdomain.net/.well-known/autoconfig/mail/config-v1.1.xml

Testing

Test the autoconfig URL from the command line:

# Mozilla autoconfig
curl -s https://autoconfig.yourdomain.net/mail/config-v1.1.xml

# Well-known path
curl -s https://yourdomain.net/.well-known/autoconfig/mail/config-v1.1.xml

# Microsoft Autodiscover
curl -s https://autodiscover.yourdomain.net/autodiscover/autodiscover.xml

# Autodiscover JSON
curl -s https://autodiscover.yourdomain.net/autodiscover/autodiscover.json

All four should return the expected XML or JSON content without certificate errors.

Test from a mail client by adding a new account with just the email address and password. The client should discover the server settings automatically without any manual input.

iOS and Android configuration

iOS Mail and Android’s default mail apps support both Mozilla autoconfig and Microsoft Autodiscover. With both configured, adding an account on a mobile device should auto-populate all settings from the email address alone.

For iOS specifically, a configuration profile (.mobileconfig) provides a more polished experience and can also configure CalDAV and CardDAV alongside mail in one step. This is covered in the mobile device management section.

Keeping the configuration accurate

Update the autoconfig XML files whenever the mail server configuration changes: port numbers, server names, or authentication methods. A stale autoconfig file causes confusion when new clients configure themselves with outdated settings.

Version control the autoconfig files alongside other server configuration using the etckeeper setup from the server tools section.

The autoconfig files are served publicly. They reveal the server hostname and port configuration for your mail server. This is not sensitive information (it is the same information any connecting mail server would discover anyway), but it is worth being aware that the configuration is publicly readable.