Thunderbird ISP hooks

  • Revision slug: Thunderbird_ISP_hooks
  • Revision title: Thunderbird ISP hooks
  • Revision id: 85616
  • Created:
  • Creator: Mscott
  • Is current revision? No
  • Comment /* Distribution */

Revision Content

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 files, 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:

  • {{template.Source("mailnews/base/ispdata/gmail.rdf")}}
  • {{template.Source("mailnews/base/ispdata/dotmac.rdf")}}
  • http://infosec.ufl.edu/tbird/Gatorlink.xml

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 {{wiki.template('Named-source', [ "mailnews/base/public/nsIMsgIncomingServer.idl", "nsIMsgIncomingServer.idl" ])}} (they automatically map to any object that's listed as "attribute" in this IDL file)
  • Identity tags match the same way for: {{wiki.template('Named-source', [ "mailnews/base/public/nsIMsgIdentity.idl", "nsIMsgIdentity.idl" ])}}
  • SMTP Server tags match the same way for: {{wiki.template('Named-source', [ "mailnews/compose/public/nsISmtpServer.idl", "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>
    <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 {{wiki.template('Named-source', [ "mailnews/base/public/nsIMsgIncomingServer.idl", "nsIMsgIncomingServer.idl" ])}} there is a generic attribute called "port". An ISP can specify a non-default port for this server by adding a line like the following to the example above:

<NC:port>555</NC:port>

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:

  • {{wiki.template('Named-source', [ "mailnews/imap/public/nsIImapIncomingServer.idl", "nsIImapIncomingServer.idl" ])}} for an IMAP server
  • {{wiki.template('Named-source', [ "mailnews/local/public/nsIPop3IncomingServer.idl", "nsIPop3IncomingServer.idl" ])}} for a POP3 server
  • {{wiki.template('Named-source', [ "mailnews/local/public/nsIMovemailIncomingServer.idl", "nsIMovemailIncomingServer.idl" ])}} for a movemail server
  • {{wiki.template('Named-source', [ "mailnews/news/public/nsINntpIncomingServer.idl", "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="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.

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.

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.

Revision Source

<h3 name="Introduction"> Introduction </h3>
<p>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.
</p><p>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. 
</p><p>This document describes how to write an ISP configuration file and how to bundle it as an extension for Thunderbird.
</p>
<h3 name="How_does_it_work"> How does it work </h3>
<p>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. 
</p><p>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. 
</p><p>Here's a screen shot of the account wizard, after adding an example ISP file:
</p><p><img alt="Image:ISPAccountwizard.png" src="File:en/Media_Gallery/ISPAccountwizard.png">
</p>
<h3 name="Building_the_ISP_File"> Building the ISP File </h3>
<p>The ISP file is a simple text files, with a UTF-8 encoding which describes the default settings for a mail account (IMAP, News, POP3, movemail) and (if appropriate) an SMTP server.
</p>
<h4 name="Existing_Examples"> Existing Examples </h4>
<p>There are several example ISP data files you can use as a template:
</p>
<ul><li> {{template.Source("mailnews/base/ispdata/gmail.rdf")}}
</li><li> {{template.Source("mailnews/base/ispdata/dotmac.rdf")}}
</li><li> http://infosec.ufl.edu/tbird/Gatorlink.xml
</li></ul>
<h4 name="Adding_Account_Properties"> Adding Account Properties </h4>
<p>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.
</p>
<ul><li> Generic server tags in the ISP file can match the attributes in <code>{{wiki.template('Named-source', [ "mailnews/base/public/nsIMsgIncomingServer.idl", "nsIMsgIncomingServer.idl" ])}}</code> (they automatically map to any object that's listed as "attribute" in this IDL file)
</li><li> Identity tags match the same way for: <code>{{wiki.template('Named-source', [ "mailnews/base/public/nsIMsgIdentity.idl", "nsIMsgIdentity.idl" ])}}</code>
</li><li> SMTP Server tags match the same way for: <code>{{wiki.template('Named-source', [ "mailnews/compose/public/nsISmtpServer.idl", "nsISmtpServer.idl" ])}}</code>
</li></ul>
<p>Note: the incoming server type is a string, either "<code>imap</code>", "<code>pop3</code>", or "<code>nntp</code>". Here's an example for defining a POP server.
</p>
<pre>&lt;!-- pop3 server info --&gt;
&lt;NC:incomingServer&gt;
  &lt;NC:nsIMsgIncomingServer&gt;
    &lt;NC:prettyName&gt;Mozilla ISP&lt;/NC:prettyName&gt;
    &lt;NC:hostName&gt;pop.example.net&lt;/NC:hostName&gt;
    &lt;NC:type&gt;pop3&lt;/NC:type&gt;
    &lt;NC:rememberPassword&gt;true&lt;/NC:rememberPassword&gt;
  &lt;/NC:nsIMsgIncomingServer&gt;
&lt;/NC:incomingServer&gt;
</pre>
<p>Changing <code>NC:type</code> to <code>imap</code> instead of <code>pop3</code> would cause the account to be created with an IMAP server.
</p><p>Looking at <code>{{wiki.template('Named-source', [ "mailnews/base/public/nsIMsgIncomingServer.idl", "nsIMsgIncomingServer.idl" ])}}</code> there is a generic attribute called "<code>port</code>". An ISP can specify a non-default port for this server by adding a line like the following to the example above:
</p>
<pre>&lt;NC:port&gt;555&lt;/NC:port&gt;
</pre>
<p>Another generic property in <code>nsIMsgIncomingServer</code> ISPs frequently like to adjust is <code>socketType</code>. Which can have a value of <code>0</code> (default socket), <code>1</code> (try TLS), <code>2</code> (always use TLS), <code>3</code> (use SSL). 
</p><p>Any of the generic attributes listed in <code>nsIMsgIncomingServer</code> can be specified here. The same holds true for the identity and SMTP settings.
</p>
<h5 name="Attributes_for_specific_server_types">Attributes for specific server types</h5>
<p>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:
</p>
<pre>&lt;NC:ServerType-imap&gt;
  &lt;NC:nsIImapIncomingServer&gt;
    &lt;NC:cleanupInboxOnExit&gt;true&lt;/NC:cleanupInboxOnExit&gt;
  &lt;/NC:nsIImapIncomingServer&gt;
&lt;/NC:ServerType-imap&gt; 
</pre>
<p>These tags match attributes in:
</p>
<ul><li><code>{{wiki.template('Named-source', [ "mailnews/imap/public/nsIImapIncomingServer.idl", "nsIImapIncomingServer.idl" ])}}</code> for an IMAP server
</li><li><code>{{wiki.template('Named-source', [ "mailnews/local/public/nsIPop3IncomingServer.idl", "nsIPop3IncomingServer.idl" ])}}</code> for a POP3 server
</li><li><code>{{wiki.template('Named-source', [ "mailnews/local/public/nsIMovemailIncomingServer.idl", "nsIMovemailIncomingServer.idl" ])}}</code> for a movemail server
</li><li><code>{{wiki.template('Named-source', [ "mailnews/news/public/nsINntpIncomingServer.idl", "nsINntpIncomingServer.idl" ])}}</code> for a news server
</li></ul>
<h5 name="Username_Requires_a_Domain">Username Requires a Domain</h5>
<p>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:  <code>incomingServerUserNameRequiresDomain</code> and <code>smtpUserNameRequiresDomain</code>.
</p><p>Here is an example SMTP server which requires a user name and the domain appended to the user name. Note that the <code>smtpUserNameRequiresDomain</code> tag appears after we close the <code>smtp</code>. 
</p>
<pre>&lt;NC:smtp&gt;
  &lt;NC:nsISmtpServer&gt;
    &lt;NC:hostname&gt;smtp.mozilla.org&lt;/NC:hostname&gt;
    &lt;NC:port&gt;465&lt;/NC:port&gt;
    &lt;NC:trySSL&gt;3&lt;/NC:trySSL&gt;
    &lt;NC:description&gt;Moco&lt;/NC:description&gt;
  &lt;/NC:nsISmtpServer&gt;
&lt;/NC:smtp&gt;

&lt;NC:smtpUserNameRequiresDomain&gt;true&lt;/NC:smtpUserNameRequiresDomain&gt;
&lt;NC:smtpRequiresUsername&gt;true&lt;/NC:smtpRequiresUsername&gt;
&lt;NC:smtpCreateNewServer&gt;true&lt;/NC:smtpCreateNewServer&gt;
&lt;NC:smtpUsePreferredServer&gt;true&lt;/NC:smtpUsePreferredServer&gt;
</pre>
<h3 name="An_Example_Configuration_File"> An Example Configuration File </h3>
<p>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". 
</p>
<pre>&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE RDF&gt;
&lt;RDF:RDF
    xmlns:NC="http://home.netscape.com/NC-rdf#"
    xmlns:RDF="http://www.w3.org/1999/02/22-rdf-syntax-ns#"&gt;

  &lt;RDF:Description about="NC:ispinfo"&gt;
    &lt;NC:providers&gt;
      &lt;NC:nsIMsgAccount about="domain:gmail.com"&gt;
        &lt;!-- pop3 server info --&gt;
        &lt;NC:incomingServer&gt;
          &lt;NC:nsIMsgIncomingServer&gt;
            &lt;NC:prettyName&gt;Gmail&lt;/NC:prettyName&gt;
            &lt;NC:hostName&gt;pop.gmail.com&lt;/NC:hostName&gt;
            &lt;NC:type&gt;pop3&lt;/NC:type&gt;
            &lt;NC:ServerType-pop3&gt;
              &lt;NC:nsIPopIncomingServer&gt;
                &lt;NC:leaveMessagesOnServer&gt;true&lt;/NC:leaveMessagesOnServer&gt;
                &lt;NC:deleteMailLeftOnServer&gt;false&lt;/NC:deleteMailLeftOnServer&gt;
              &lt;/NC:nsIPopIncomingServer&gt;
            &lt;/NC:ServerType-pop3&gt;
            &lt;NC:loginAtStartUp&gt;true&lt;/NC:loginAtStartUp&gt;
            &lt;NC:downloadOnBiff&gt;true&lt;/NC:downloadOnBiff&gt;
            &lt;NC:rememberPassword&gt;true&lt;/NC:rememberPassword&gt;
            &lt;NC:port&gt;995&lt;/NC:port&gt;
            &lt;NC:socketType&gt;3&lt;/NC:socketType&gt;
          &lt;/NC:nsIMsgIncomingServer&gt;
        &lt;/NC:incomingServer&gt;

        &lt;!-- smtp server info --&gt;
        &lt;NC:smtp&gt;
          &lt;NC:nsISmtpServer&gt;
            &lt;NC:hostname&gt;smtp.gmail.com&lt;/NC:hostname&gt;
            &lt;NC:port&gt;587&lt;/NC:port&gt;
            &lt;NC:trySSL&gt;2&lt;/NC:trySSL&gt;
            &lt;NC:description&gt;Gmail&lt;/NC:description&gt;
          &lt;/NC:nsISmtpServer&gt;
        &lt;/NC:smtp&gt;
        &lt;NC:smtpRequiresUsername&gt;true&lt;/NC:smtpRequiresUsername&gt;
        &lt;NC:smtpCreateNewServer&gt;true&lt;/NC:smtpCreateNewServer&gt;
        &lt;NC:smtpUsePreferredServer&gt;true&lt;/NC:smtpUsePreferredServer&gt;

        &lt;!-- identity defaults --&gt;
        &lt;NC:identity&gt;
          &lt;NC:nsIMsgIdentity&gt;
          &lt;/NC:nsIMsgIdentity&gt;
        &lt;/NC:identity&gt;

        &lt;!-- other options --&gt;
        &lt;NC:wizardSkipPanels&gt;true&lt;/NC:wizardSkipPanels&gt;
        &lt;NC:wizardShortName&gt;Gmail&lt;/NC:wizardShortName&gt;
        &lt;NC:wizardLongName&gt;Gmail&lt;/NC:wizardLongName&gt;
        &lt;NC:wizardShow&gt;true&lt;/NC:wizardShow&gt;
        &lt;NC:wizardPromote&gt;true&lt;/NC:wizardPromote&gt;
        &lt;NC:emailProviderName&gt;Gmail&lt;/NC:emailProviderName&gt;
        &lt;NC:sampleEmail&gt;example@gmail.com&lt;/NC:sampleEmail&gt;
        &lt;NC:sampleUserName&gt;example&lt;/NC:sampleUserName&gt;
        &lt;NC:emailIDDescription&gt;Gmail Username:&lt;/NC:emailIDDescription&gt;
        &lt;NC:showServerDetailsOnWizardSummary&gt;true&lt;/NC:showServerDetailsOnWizardSummary&gt;
      &lt;/NC:nsIMsgAccount&gt;
    &lt;/NC:providers&gt;
  &lt;/RDF:Description&gt;
&lt;/RDF:RDF&gt;
</pre>
<h3 name="Testing"> Testing  </h3>
<p>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 &lt;path to thunderbird.exe&gt;\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.
</p>
<h3 name="Distribution"> Distribution </h3>
<p>Now that you have a working configuration file for an ISP or webmail provider, you need to distribute it. 
</p><p>There are two ways to do this: as an extension or distributing a custom build.
</p>
<h4 name="As_an_Extension"> As an Extension </h4>
<p>Configuration files can be installed in Thunderbird 2 using the Mozilla Extension system. You can host the extension on <a class="external" href="https://addons.mozilla.org/thunderbird/extensions/">Mozilla Add-ons</a>.
</p><p>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. 
</p>
<h4 name="Custom_Builds"> Custom Builds </h4>
<p>If you are distributing a customized version of Thunderbird 2, simply add the RDF or XML to <code>$INSTALLFOLDER/isp/</code> where <code>$INSTALLFOLDER</code> is the location of <code>thunderbird.exe</code>. Thunderbird looks in this directory for these RDF files.
</p><p>Note: For Thunderbird 1.5.0.x, the direction location you should use is: <code>$INSTALLFOLDER/defaults/isp</code>.
</p>
Revert to this revision