Thunderbird ISP hooks

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:

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.

<!-- 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>
    <NC:rememberPassword>true</NC:rememberPassword>
  </NC:nsIMsgIncomingServer>
</NC:incomingServer>

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

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

<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="http://home.netscape.com/NC-rdf#"
    xmlns:RDF="http://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>
            <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>example@gmail.com</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.

Related Information

There's related information on automatically obtaining the e-mail settings at http://wiki.mozilla.org/Tb:Autoconfiguration. Discussion on this is taking place in news://news.mozilla.org:119/mozilla....ps.thunderbird (Subject: Proposal: Auto-configuration, Date: 2008-03-04)