Thunderbird ISP hooks

  • Revision slug: Thunderbird_ISP_hooks
  • Revision title: Thunderbird ISP hooks
  • Revision id: 85593
  • Created:
  • Creator: Yoshino
  • Is current revision? No
  • Comment

Revision Content

Introduction

One of the big challenges ISPs face in deploying e-mail software to their customers involves creating mail accounts for users. ISPs have to document and spend a lot of time helping users with ISP specific information such as the mail server name, authentication options, SSL, SMTP server name, etc.

Thunderbird has hooks which makes account creation easy for ISP customers. In most instances, a new user only needs to know the user name associated with the ISP account, Thunderbird can automatically fill in the rest of the account details.

How does it work

The idea is fairly straightforward. An ISP can list all of its account setting information in a .rdf or .xml file. This file can be distributed with Thunderbird by the ISP or it can be installed as an extension by the user. Thunderbird looks for these ISP files at start up, adding a new account type for each one in the New Account Wizard Dialog. When the user chooses to create a new account with the ISP, the wizard only needs to prompt the user for his name and user name. The rest of the account information comes from the ISP provided 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.

Existing Examples

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

  • http://infosec.ufl.edu/tbird/Gatorlink.xml
  • http://lxr.mozilla.org/seamonkey/source/mailnews/base/ispdata/aol.rdf

Adding Account Properties

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

  • Generic server tags in the ISP file can match the attributes in

http://lxr.mozilla.org/seamonkey/source/mailnews/base/public/nsIMsgIncomingServer.idl (they automatically map to any object that's listed as "attribute" in this IDL file)

  • Identity tags match the same way for:

http://lxr.mozilla.org/seamonkey/source/mailnews/base/public/nsIMsgIdentity.idl

  • SMTP Server tags match the same way for:

http://lxr.mozilla.org/seamonkey/source/mailnews/compose/public/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 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.

Distribution

Now that you have a file which specifies the default values for your ISP settings, how do you get it into the hands of your users?

There are two ways to do this.

Custom Builds

If you are distributing a customized version of Thunderbird, simply add the .rdf or .xml to $INSTALLFOLDER/default/isp where $INSTALLFOLDER is the location of thunderbird.exe. Thunderbird automatically looks in this directory location for any .rdf and .xml files.

As an Extension

ISP Account files can be installed in Thunderbird using the Mozilla Extension system. You can even host an extension for your ISP on http://addons.mozilla.org.

yoshino: ispexample.xpi is just a sample I made. Please replace it with generic one... We've already created an existing extension you can use as a template: http://www.mozilla.org/projects/thunderbird/specs/ispexample.xpi. Open the .xpi file using your favorite zip utility. Rename dion.rdf, adjust the account specific information in the newly renamed .rdf file and zip the files into yourisp.xpi. We encourage ou to submit your ISP XPI as an extension on addons.mozilla.org.

Revision Source

<h3 name="Introduction"> Introduction </h3>
<p>One of the big challenges ISPs face in deploying e-mail software to their customers involves creating mail accounts for users. ISPs have to document and spend a lot of time helping users with ISP specific information such as the mail server name, authentication options, SSL, SMTP server name, etc.
</p><p>Thunderbird has hooks which makes account creation easy for ISP customers. In most instances, a new user only needs to know the user name associated with the ISP account, Thunderbird can automatically fill in the rest of the account details.
</p>
<h3 name="How_does_it_work"> How does it work </h3>
<p>The idea is fairly straightforward. An ISP can list all of its account setting information in a .rdf or .xml file. This file can be distributed with Thunderbird by the ISP or it can be installed as an extension by the user. Thunderbird looks for these ISP files at start up, adding a new account type for each one in the New Account Wizard Dialog. When the user chooses to create a new account with the ISP, the wizard only needs to prompt the user for his name and user name. The rest of the account information comes from the ISP provided 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. 
</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> http://infosec.ufl.edu/tbird/Gatorlink.xml
</li><li> http://lxr.mozilla.org/seamonkey/source/mailnews/base/ispdata/aol.rdf
</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 user identity. Each object has its own settings which can be specified in this ISP file.
</p>
<ul><li> Generic server tags in the ISP file can match the attributes in
</li></ul>
<p>http://lxr.mozilla.org/seamonkey/source/mailnews/base/public/nsIMsgIncomingServer.idl
(they automatically map to any object that's listed as "attribute" in this IDL file)
</p>
<ul><li> Identity tags match the same way for:
</li></ul>
<p>http://lxr.mozilla.org/seamonkey/source/mailnews/base/public/nsIMsgIdentity.idl
</p>
<ul><li> SMTP Server tags match the same way for:
</li></ul>
<p>http://lxr.mozilla.org/seamonkey/source/mailnews/compose/public/nsISmtpServer.idl
</p><p>Note: the incoming server type is a string, either "imap", "pop3", or "nntp". Here's an example for defining a POP server. 
</p>
<pre class="eval">       <span class="comment">pop3 server info</span>
       &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 NC:type to imap instead of pop3 would cause the account to be created with an IMAP server.
</p><p>Looking at <a class="external" href="http://lxr.mozilla.org/seamonkey/source/mailnews/base/public/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:
</a></p><a class="external" href="http://lxr.mozilla.org/seamonkey/source/mailnews/base/public/nsIMsgIncomingServer.idl">
<pre class="eval">       &lt;NC:port&gt;555&lt;/NC:port&gt;
</pre>
<p>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). 
</p><p>Any of the generic attributes listed in nsIMsgIncomingServer can be specified here. The same holds true for the identity and SMTP settings.
</p>
<h3 name="Distribution"> Distribution </h3>
<p>Now that you have a file which specifies the default values for your ISP settings, how do you get it into the hands of your users? 
</p><p>There are two ways to do this. 
</p>
<h4 name="Custom_Builds"> Custom Builds </h4>
<p>If you are distributing a customized version of Thunderbird, simply add the .rdf or .xml to $INSTALLFOLDER/default/isp where $INSTALLFOLDER is the location of thunderbird.exe. Thunderbird automatically looks in this directory location for any .rdf and .xml files.
</p>
<h4 name="As_an_Extension"> As an Extension </h4>
<p>ISP Account files can be installed in Thunderbird using the Mozilla Extension system. You can even host an extension for your ISP on http://addons.mozilla.org.
</p><p><span class="comment">yoshino: ispexample.xpi is just a sample I made. Please replace it with generic one...  We've already created an existing extension you can use as a template: http://www.mozilla.org/projects/thunderbird/specs/ispexample.xpi.  Open the .xpi file using your favorite zip utility. Rename dion.rdf, adjust the account specific information in the newly renamed .rdf file and zip the files into yourisp.xpi. We encourage ou to submit your ISP XPI as an extension on addons.mozilla.org.</span>
</p></a>
Revert to this revision