Mozilla Thunderbird ISP Autoconfiguration Script for PHP and Apache

Starting with version 3.1, Mozilla Thunderbird has a built-on feature for automatically discovering mail server settings. While the default operation of "guessing" the setup works great 90% of the time, there is a feature that will "look-up" the correct settings for the given email address.

ISPAutoConfig PHP script for Mozilla Thunderbird.

This feature is very useful for Internet Service Providers that want their client's email to just work automatically. It's possible to just create the required XML file as documented and place it on a webserver. However, if you are an ISP that hosts several email domains, this route is in-efficient.

The ISPAutoConfig PHP script is designed for anyone who hosts multiple domains. This early version is very specific on configuration, but should work just fine for anyone who needs it. It uses the following template.

  • Incoming Server (IMAP 143 or POP3 110): mail.EMAIL_DOMAIN
  • Outgoing Server (SMTP 587,25): mail.EMAIL_DOMAIN
  • Username: EMAIL_ADDRESS
  • Plain Text no SSL or TLS authentication for both incoming and outgoing servers*

The above template is a very standard setup for ISP's that host multiple domains on their mail systems.


  • Access to your DNS server for your email domain(s).
  • Apache with URL Rewriting enabled (this script was developed on version 2.2.x).
  • PHP 5.2 or greater (this script was developed on version 5.3.x).
  • Mozilla Thunderbird 3.1 or greater.
  • This script assumes that your e-mail system setup in a matter that is compatible with the template shown above.

Setup your DNS

The first step which is un-avoidable in any circumstance is that everyone of your domains needs a new DNS record added. For every domain that you want to support Thunderbird Autoconfiguration for, you must add and A or CNAME record that points to the webserver that you will host the Autoconfiguration script on.

autoconfig IN CNAME autoconfig.<WEBSERVER>.tld.

The above example is a CNAME (alias) that will resolve to our autoconfig server. Please note, that "autoconfig..tld" must be an A record and must point to a webserver that is listening for requests on "autoconfig..tld".

Setup Apache

You may use an Apache virtual name host to serve your configuration file. Your server will need to answer to every domain that you have enabled for Auto configuration. You could add each domain one by one, but this is in-efficient. Instead, add the following wildcard directive to your Apache virtual name host configuration.

Alias autoconfig.*

The above directive will make Apache serve this virtual host for every sub domain named "autoconfig" regardless of the domain name. Go ahead and apply the changes and give it a test run. Every domain should be sent to the same virtual name host.

Next Assuming you have properly enabled URL Rewriting on your Apache server, you just need to extract the archive so the following 3 files are on the virtual server's document root.

The download link to the script is located at the bottom of this page.

  • .htaccess
  • autoconfig.php

You should be able to call up a the Autoconfiguration URL in your web browser and an XML file with the default configuration will be displayed.
http://autoconfig..tld/mail/config-v1.1.xml. If this is not the case, please make sure that URL Rewriting is properly setup, or copy and paste the contents on the ".htaccess" file directly in your Apache named virtual host directives.

Customize The Settings

Most of the default settings will work fine for the given template. However, you may want to adjust some items like the "emailProvider ID", "Documentation" link, and support "Description".

The Email Provider ID can be changed on line 101 of the file. Just replace "" with anything you want. Keep it simple, do not use spaces or any strange characters.

$attr->appendChild($this->DOC->createTextNode("<PUT ANYTHING>"));

The support Description can be changed on line 155 of the file. Just replace "" with anything you want.

//Description of Support Link
$desc = $this->DOC->createElement("descr", "<PUT ANYTHING>");

The Documentation link can be changed on line 48 of the file. Just replace "" with a URL to your email support page.

private $URL = '<PUT ANYTHING>';

Being 100% open source and under the BSD license, you are free to modify the code to make it do what you need. Currently, only plain text authentication is supported in the IMAP, POP3, and SMTP settings. The framework is their to add support for TLS and SSL connections*.

Final Notes

*Keep in mind that SSL/TLS connection do not support multiple host names. You will need to use your primary mail server hostname as the server address.

Mozilla Thunderbird currently complains with a big scary red dialog when you use plain text authentication. While I am a big supporter of security, I do not agree with this operation, it is technically impossible to install an SSL/TLS certificate and keep the elegance of having the client utilize their own DNS domain for their server settings. Please support the change of this behavior and report bugs/feature requests

File ISPAutoconfig.7z2.53 KB