Add-ons

An overview of Thunderbird components

This content covers features introduced in Thunderbird 3

Draft
This page is not complete.

The Thunderbird mail application is a group of components built on a set of technologies that can seem daunting to new developers. However, in many cases you only need to learn a few concepts to write an extension.

The purpose of this article is to:

  • describe the Thunderbird user interface and provide the standard terms for interface elements
  • discuss some example modifications that could be made via Thunderbird extensions
  • introduce some of the APIs that are most commonly used by extension developers

To dive right in, see Building a Thunderbird extension or the general information about development tools and environment. To read the notes embedded in the Thunderbird source code, check out comm-central.

(There are some UML diagrams of Thunderbird's underlying architecture. However, their complexity means they are generally beyond what is needed by extension developers. Also, there is some documentation on the Activity Manager (which displays events and process activity to the user) but these are also probably beyond the scope of extension developers' needs.)

Background - the big picture

Message flow

What happens to incoming messages?

  1. establish connection with server (via Accounts and the Login Manager)
  2. validate user credentials
  3. ...

What happens to outgoing messages?

  1. user composes the message
  2. Thunderbird establishes connection with server (link to Accounts section)
  3. ...

TODO

Accounts

Thunderbird users usually configure several accounts. (In the Thunderbird code and documentation, accounts are also referred to as "servers".) There are accounts for incoming mail messages (POP and IMAP, and Gmail and .Mac services); accounts for outgoing messages (SMTP); and accounts for incoming and outgoing newsgroup messages (NNTP). Users can also configure accounts for syndicated news and blogs (RSS). After they have been created, accounts are displayed as top-level containers in the Folder pane. (The MailNews Protocols article discusses Thunderbird's implementation of these protocols.)

Accounts are created and configured in the Account Manager (Tools | Account Settings).

See the Accounts interfaces page for a description of related interfaces. 

Alternatively, view the source code in the Mozilla Cross-Reference:Edit section

Things extensions can do with accounts

Login Manager

The Login Manager is a component shared by Thunderbird and Firefox that stores username / password combinations in encrypted format. Refer to the Using nsILoginManager article for more information about this component.

View the source code in the Mozilla Cross-Reference:Edit section

TODO

Folder pane

The folder pane is displayed by default on the left side of the Thunderbird interface.

When Thunderbird is installed it creates the "Local Folders" container. When users create mail accounts, they can elect to store the messages either in the "Local Folders" container or in a top-level container specific to the account. (This allows messages from multiple POP3 accounts to be optionally aggregated into a single container.) Therefore, the folder pane will show the "Local Folders" container, any mail accounts that were configured to use their own top-level container, and any RSS or newsgroup account.

Users can create folders beneath top-level containers (except for newsgroups accounts). Folders can contain other folders and / or messages.

Folders are a key data structure in Thunderbird. Thunderbird uses one  database per folder (nsIMsgDbFolder), which is designed to optimize folder performance. These databases store information from the message header, so lists of messages in folders can be displayed and sorted very quickly, even if the messages themselves are large. (These headers are nsIMsgDbHdr objects.) Each folder also has a database called the "off-line cache" that stores the complete messages (including headers, bodies and attachments) that have already been downloaded from the server.

(See also the section on Gloda, which is a multi-folder database introduced in Thunderbird 3.)

Users can create folders that contain messages that match specific search criteria. These are called "virtual folders" or "saved searches".

Smart folders aggregate similar types of messages from POP3 and IMAP accounts, so that, for example, a single inbox contains messages from the inboxes of all configured accounts. To access smart folders, use the arrows at the top of the folder panel.

The Folder pane interfaces page describes the relevant interfaces.

Alternatively, view the source code in the Mozilla Cross-Reference:Edit section

  • nsIMsgDatabase: an abstract interface used to access the mail database backend
  • nsIMsgFolder: an interface used to interact with folders
  • nsIMsgDbFolder?
  • off-line cache IDL?

Things extensions can do with folders

TODO

  • smart folders (when done)
  • Update the related interfaces list and expand the description on the Folder pane interfaces page
  • write "Iterate over all messages in a folder" example
  • write "Add views to the Folder Pane" example (link is for a stub page)
  • extension to write a new folderpane mode

Message list

The message list is displayed by default on the top right area of the Thunderbird interface. It summarizes (in column form) all the messages in the selected folder.

See Message list interfaces for a description of the related interfaces.

Things extensions can do with the message list

TODO

Message window

The contents of the message selected in the message list are displayed in the message window. Alternatively, messages can be displayed in a tab or in a separate window.

Message headers are meta information about an email message. They consist of name / value pairs. Message headers are defined in several RFCs. User agents can also create custom headers, as long as they adhere to the definition in the RFC. By default, Thunderbird displays a subset of a message's headers (the "from" address, subject, recipient, etc) above the body of the message.

As of Thunderbird 3.0, the compact message header view (which allowed the user to reduce the size of the message header to a single line) was removed from the Thunderbird core. That means that the only view is the default, which shows a number of message headers and several icons (reply, forward, etc). Message header display can be customized via extensions (for example, the Header Design Inc and the Compact Header extensions).

See the Message interfaces page for a description of the related interfaces.

Alternatively, view the source code in the Mozilla Cross-Reference:Edit section

Things extensions can do with message headers

TODO

  • expand description - what is relevant or interesting to extension developers?
  • validate text and interface list
  • more examples, listed above and on the Message example page

Address Book

Thunderbird's main address book management functions are built on a few key concepts:

  • A Contact is an entry corresponding to a person (or the equivalent, for example the address for a group), including email address, first and last name, phone number, etc.
  • A List is a set of email addresses that can be referred to with a single nickname. For example, a user might group all the members of their work team under the List name "Team". The user could then send a message to all the addresses included in the List by specifying the list name as the message recipient.
  • An Address Book is a collection of contacts and lists. By default, Thunderbird creates two address books: a user-defined address book (which is manually maintained by the user), and a "Collected address" book (where Thunderbird stores the addresses of recipients of messages to which users apply. On Macintosh systems, there is also a Mac OS X address book that reads (but does not write) the system address book. If the user configures an LDAP server, there will be another read-only address book that contains the addresses stored on the LDAP server.

The contact sidebar is displayed in the message composition window (invoked from the View menu). When enabled, users can select address books and assign recipient emails.

See the the Address book interfaces page for a description of the related interfaces.

Alternatively, view the source code in the Mozilla Cross-Reference:Edit section

Things extensions can do with the address book

Global components

The items in this section are not component-specific. They can apply to more than one aspect of Thunderbird.

Global database (gloda)

While the folder-centric structure described above is good for many things, it makes it hard to do manipulations on messages that span different folders. (For example, multiple folder databases need to be open and kept in memory at the same time, indices are inefficient to maintained, etc.)

In Thunderbird 3, there is a new database layer called "gloda" (short for "global database"), which provides multi-folder capabilities. Gloda functionality enables searching across multiple accounts for specific message parameters (such as email address, the existence of an attachment, receipt within a time range, etc).

See the gloda page for more information about how gloda works. See Creating a gloda message query for information about implementing gloda. See Gloda examples for more use cases.

See the gloda page for information about its interfaces.

Things extensions can do with Gloda

STEEL

STEEL is the Scriptable Thunderbird Easy Extension Library. Similar to Firefox's FUEL, it is JavaScript library designed to help developers build extensions using terminology and interfaces that are familiar to them. like set of interfaces to facilitate Thunderbird extension development. The steelIApplication interface implements all the functions of extIApplication.

See the STEEL interfaces page for information about the related interfaces.

Alternatively, view the source code in the Mozilla Cross-Reference:

Document Tags and Contributors

Tags: 
 Contributors to this page: aswin5, wbamberg, realraven, jenzed, caurton, Jcranmer
 Last updated by: aswin5,