Thunderbird ISP hooks

Deprecated
This feature has been removed from the Web standards. Though some browsers may still support it, it is in the process of being dropped. Do not use it in old or new projects. Pages or Web apps using it may break at any time.

This format is no longer supported in Thunderbird 3 in favor of Autoconfiguration.

Introduction

Getting started with Thunderbird can be daunting for many users who use it to access e-mail from an ISP or a webmail provider. Users need to know specific information such as the mail server name, POP or IMAP, authentication options, security settings such as SSL/TLS, the SMTP server name, etc. Many ISPs and web mail providers must maintain online documentation walking a user through account setup in different mail clients with all of the various settings.

Thunderbird now has hooks which makes account creation easy for ISP and webmail users. A new user provides the email address associated with the account and Thunderbird figures out the rest of the account details. Thunderbird 2 ships with ISP information for gmail and dotmac accounts. We'd like to add more in future releases. Additional ISP configurations can be installed as extensions.

This document describes how to write an ISP configuration file and how to bundle it as an extension for Thunderbird.

How does it work

The idea is fairly straightforward. The account settings for an ISP or webmail provider are specified in an RDF or XML file. This file can be installed as an extension by the user.

Thunderbird looks for these configuration files, adding a new account type for each one to the account wizard. The user provides his name and user name, the rest of the account settings come from the configuration file.

Here's a screen shot of the account wizard, after adding an example ISP file:

Image:ISPAccountwizard.png

Building the ISP file

The ISP file is a simple text file, with a UTF-8 encoding which describes the default settings for a mail account (IMAP, News, POP3, movemail) and (if appropriate) an SMTP server.

Existing examples

There are several example ISP data files you can use as a template:

https://infosec.ufl.edu/tbird/Gatorlink.rdf

On Mozilla Add-ons, you can download or directly view the sources of the followings Add-ons:

Adding account properties

A mail account has several objects associated with it: a mail server, SMTP server, and a user identity. Each object has its own settings which can be specified in the configuration file.

Generic server tags in the ISP file can match the attributes in nsIMsgIncomingServer.idl (they automatically map to any object that's listed as "attribute" in this IDL file)
Identity tags match the same way for: nsIMsgIdentity.idl
SMTP Server tags match the same way for: nsISmtpServer.idl

Note: the incoming server type is a string, either "imap", "pop3", or "nntp". Here's an example for defining a POP server.

<!-- pop3 server info -->
<NC:incomingServer>
  <NC:nsIMsgIncomingServer>
    <NC:prettyName>Mozilla ISP</NC:prettyName>
    <NC:hostName>pop.example.net</NC:hostName>
    <NC:type>pop3</NC:type>
    <!--
        On Thunderbird 3, following setting causes "TypeError: dest.setBoolAttribute is not a function"
        and breaks the account which is going to be created.
        <NC:rememberPassword>true</NC:rememberPassword>
    -->
  </NC:nsIMsgIncomingServer>
</NC:incomingServer>

Changing NC:type to imap instead of pop3 would cause the account to be created with an IMAP server.

Looking at nsIMsgIncomingServer.idl there is a generic attribute called "port". An ISP can specify a non-default port for this server by introducing the port attribute to the nsIMsgIncomingServer:

<NC:incomingServer>
  <NC:nsIMsgIncomingServer>
  ..
  <NC:port>555</NC:port>
  ..
  </NC:nsIMsgIncomingServer>
</NC:incomingServer>

Another generic property in nsIMsgIncomingServer ISPs frequently like to adjust is socketType. Which can have a value of 0 (default socket), 1 (try TLS), 2 (always use TLS), 3 (use SSL).

Any of the generic attributes listed in nsIMsgIncomingServer can be specified here. The same holds true for the identity and SMTP settings.

Attributes for specific server types

In addition to the generic attributes, some attributes only apply to a specific type of incoming server. Specify these in a separate section inside the server info. Here is an example for an IMAP server:

<NC:ServerType-imap>
  <NC:nsIImapIncomingServer>
    <NC:cleanupInboxOnExit>true</NC:cleanupInboxOnExit>
  </NC:nsIImapIncomingServer>
</NC:ServerType-imap>

These tags match attributes in:

nsIImapIncomingServer.idl for an IMAP server
nsIPop3IncomingServer.idl for a POP3 server
nsIMovemailIncomingServer.idl for a movemail server
nsINntpIncomingServer.idl for a news server

Username requires a domain

Some ISPs and webmail providers require the domain name to be appended to the user name for use with the mail server and/or the smtp server. This requirement can be specified by using the following tags in the configuration file: incomingServerUserNameRequiresDomain and smtpUserNameRequiresDomain.

Here is an example SMTP server which requires a user name and the domain appended to the user name. Note that the smtpUserNameRequiresDomain tag appears after we close the smtp.

<NC:smtp>
  <NC:nsISmtpServer>
    <NC:hostname>smtp.mozilla.org</NC:hostname>
    <NC:port>465</NC:port>
    <NC:trySSL>3</NC:trySSL>
    <NC:description>Moco</NC:description>
  </NC:nsISmtpServer>
</NC:smtp>

<NC:smtpUserNameRequiresDomain>true</NC:smtpUserNameRequiresDomain>
<NC:smtpRequiresUsername>true</NC:smtpRequiresUsername>
<NC:smtpCreateNewServer>true</NC:smtpCreateNewServer>
<NC:smtpUsePreferredServer>true</NC:smtpUsePreferredServer>

An example configuration file

Here's the RDF file we generate for gmail support. If you copy this example, be sure to change the about attribute from "domain:gmail.com".

<?xml version="1.0"?>
<!DOCTYPE RDF>
<RDF:RDF
    xmlns:NC="https://home.netscape.com/NC-rdf#"
    xmlns:RDF="https://www.w3.org/1999/02/22-rdf-syntax-ns#">

  <RDF:Description about="NC:ispinfo">
    <NC:providers>
      <NC:nsIMsgAccount about="domain:gmail.com">
        <!-- pop3 server info -->
        <NC:incomingServer>
          <NC:nsIMsgIncomingServer>
            <NC:prettyName>Gmail</NC:prettyName>
            <NC:hostName>pop.gmail.com</NC:hostName>
            <NC:type>pop3</NC:type>
            <NC:ServerType-pop3>
              <NC:nsIPopIncomingServer>
                <NC:leaveMessagesOnServer>true</NC:leaveMessagesOnServer>
                <NC:deleteMailLeftOnServer>false</NC:deleteMailLeftOnServer>
              </NC:nsIPopIncomingServer>
            </NC:ServerType-pop3>
            <NC:loginAtStartUp>true</NC:loginAtStartUp>
            <NC:downloadOnBiff>true</NC:downloadOnBiff>
            <!--
                On Thunderbird 3, following setting causes "TypeError: dest.setBoolAttribute is not a function"
                and breaks the account which is going to be created.
                <NC:rememberPassword>true</NC:rememberPassword>
            -->
            <NC:port>995</NC:port>
            <NC:socketType>3</NC:socketType>
          </NC:nsIMsgIncomingServer>
        </NC:incomingServer>

        <!-- smtp server info -->
        <NC:smtp>
          <NC:nsISmtpServer>
            <NC:hostname>smtp.gmail.com</NC:hostname>
            <NC:port>587</NC:port>
            <NC:trySSL>2</NC:trySSL>
            <NC:description>Gmail</NC:description>
          </NC:nsISmtpServer>
        </NC:smtp>
        <NC:smtpRequiresUsername>true</NC:smtpRequiresUsername>
        <NC:smtpCreateNewServer>true</NC:smtpCreateNewServer>
        <NC:smtpUsePreferredServer>true</NC:smtpUsePreferredServer>

        <!-- identity defaults -->
        <NC:identity>
          <NC:nsIMsgIdentity>
          </NC:nsIMsgIdentity>
        </NC:identity>

        <!-- other options -->
        <NC:wizardSkipPanels>true</NC:wizardSkipPanels>
        <NC:wizardShortName>Gmail</NC:wizardShortName>
        <NC:wizardLongName>Gmail</NC:wizardLongName>
        <NC:wizardShow>true</NC:wizardShow>
        <NC:wizardPromote>true</NC:wizardPromote>
        <NC:emailProviderName>Gmail</NC:emailProviderName>
        <NC:sampleEmail>[email protected]</NC:sampleEmail>
        <NC:sampleUserName>example</NC:sampleUserName>
        <NC:emailIDDescription>Gmail Username:</NC:emailIDDescription>
        <NC:showServerDetailsOnWizardSummary>true</NC:showServerDetailsOnWizardSummary>
      </NC:nsIMsgAccount>
    </NC:providers>
  </RDF:Description>
</RDF:RDF>

Testing

When developing the creation of an ISP configuration file, it is helpful to be able to quickly test the settings you are working on without installing it as an extension. You can do this by placing a copy of the configuration file in <path to thunderbird.exe>\isp\. gmail.rdf and rss.rdf should already be in this location. Restart Thunderbird and your account type will be listed in the account wizard.

Distribution

Now that you have a working configuration file for an ISP or webmail provider, you need to distribute it.

There are two ways to do this: as an extension or distributing a custom build.

As an extension

Configuration files can be installed in Thunderbird 2 using the Mozilla Extension system. You can host the extension on Mozilla Add-ons.

The extension needs to include the configuration file in a subdirectory called isp. Thunderbird 2.0.0.x walks through the list of enabled extensions looking for directories named isp. The account wizard is populated with any RDF or XML configuration files it finds in these locations.

Sample extension

Here is an example extension you can use as a template: Media:Example-isp.xpi. Download this file locally. XPI files are actually ZIP files can be extraced using any zip program like WinZIP.

Custom builds

If you are distributing a customized version of Thunderbird 2, simply add the RDF or XML to $INSTALLFOLDER/isp/ where $INSTALLFOLDER is the location of thunderbird.exe. Thunderbird looks in this directory for these RDF files.

Note: For Thunderbird 1.5.0.x, the direction location you should use is: $INSTALLFOLDER/defaults/isp.