Documentation for Thunderbird Address Book/Android Contacts Synchronization app

Last updated Oct. 30, 2011

Changes and Bug Fixes

What is this app and should you use it?

Getting Started


Main Screen and Menu


Known Issues and FAQs


Changes and Bug Fixes

Version 2.0.1

  • Minor bug fixes for null pointers on system exceptions

  • Longer timeout for auto-scan (more tolerant of network slowdown).

  • Thunderbird 7 support

Version 2.0

  • NEW: auto-scan IP addresses for Thunderbird host

  • NEW: encode transmitted data

NEW: improved contact sync (automatic delete of contacts)

  • NEW: Android Market required license check for paid app (Internet connection required)

  • Updated interface. Touch the "Settings" text to make the settings buttons appear/disappear.

Version 1.3.1

  • Fixed bug with synchronizing contacts with organization/company data.

Version 1.3

  • Fixed bug for contacts with lots of data (for example, notes greater than 2Kb).

Version 1.2

  • Fixed bug with international characters encoding: verified correctly works for special European characters, Chinese, and Japanese.

  • For Android 2.0+, added sync of 1 IM name, 1 nickname, 2 web pages, and birthday.

Version 1.1

  • Added detection of Sync operation crashing.

  • Fixed memory leaked: this caused large address books/groups to fail import though the app didn't report any problems.

  • Compatibility with Thunderbird 3.1

  • Fixed for 2.0+ users: groups that the app won't sync were listed as available in the Sync settings. Added a setting to optionally Sync any group.

  • Issue with Google Contact sync "hijacking" contacts (see the Known Issues for details).

Version 1.0

  • Improved Sync for Android 2.0 and later: only contacts that have changed since the last sync will be transferred. Individual contact fields can be emptied/deleted. A complete Sync operation must be performed once to setup the internal data to do this. For pre-2.0 users, there is an OS bug that prevents this feature from working fully (see the Known Issues for details).

  • Fixed a bug with the server communication that could cause multiple messages to be sent together (which the server won't recognize).

  • For Android 2.0+, a bug in group creation caused empty groups to be created to your online account. This has been fixed but to put it into effect, you should import your Thunderbird Address books again after upgrading from version 0.8.

  • With this version, this app is becoming trial ware. No features are disabled in the trial version, but there is a pop-up suggesting you get the pay version. Also, future updates and fixes may be limited to the pay version. The pay version is available on Android Market.

What is this app and should you use it?

This app, when used with the Thunderbird extension Android Contacts Sync, provides direct transfer of Thunderbird Address Book and Android Contacts data via a TCP/IP network connection. I wrote this app so I would not have to upload address book/contacts data to an online account such as Gmail. If you would like to synchronize address book/contacts data between Thunderbird, your Google account, and an Android device, I recommend you do not use this app. Instead use a Thunderbird extension specifically for syncing to your Google account and setup your Android device to sync with your Google Contacts.

I wrote this app so I could keep my personal contact data in just two places, my PC and my phone, and not be forced to upload it online. If that is what you are looking for, this is the app for you. Please see the Known Issues for limitations.

System requirements:

Thunderbird 3.0 or later

Android device running 1.5 to 2.3

Network connection between your Thunderbird PC and Android device.

Getting Started

For further reference in this document, menu selections will be noted by a notation such as Menu>Help, which in this example means select the menu named Menu (or push the Menu button), then select the Help items.

As mentioned above, you will need to install the Thunderbird extension Android Contacts Sync which this app will communicate with. It is available on with the trial version of the app. Download the extension file and rename the file to end with .xpi or it will not install properly in Thunderbird. You can install it by selecting Tools>Add-Ons>Extensions, then select Install Add-on From File from the drop-down menu next to the search box near the top (for Thunderbird 3.* click the Install button) and browse to the file. After installing the extension, open the extension options by selecting Tools>Add-Ons>Extensions>Android Contacts Sync>Options. Change the Key entry. Remember this key. You will need to enter the same key in the Android app.

Before you can perform a sync operation, you must enter the connection data so that the app can connect to the host running Thunderbird. Start up the app and touch Settings to make the settings buttons appear and click the Connection button. Or just press the Sync button on the main screen and the Connection setting screen will come up if there are no current settings.

Check “Scan for Thunderbird”. Change the key in the bottom box to be the same as you entered in the Thunderbird extension.

Be sure you have Thunderbird running before attempting to sync. Thunderbird must be running with the main messaging window open (this is the window where you can see your Inbox).

After entering your Connection settings, return to the main screen and press the Sync button. Even with no sync settings, the app will attempt to connect to Thunderbird and get the names of your address books. If successful, you should see a completion message below the Sync button. If there was a problem, you will get a message in an alert popup.

After a successful sync operation, go to the Group/Address Book Sync Settings to setup how Address Book/Contact Group data should be transferred.

If you have trouble connecting, try changing the Connection Settings.


As you would expect with each new version, certain bugs will be fixed. If you have problems after updating to the latest version, try resetting your contacts:

  1. Export your contacts to Thunderbird, if possible.

  2. Clear the contacts data on your Android device: from the Android main screen select Menu>Settings>Applications>Manage Applications, then select Contacts Storage (2.0+ users will need to set Filters to All to see Contacts Storage). Select Clear Data to clear your contacts database.

  3. In Thunderbird, select Tools>Reset Android Contacts Sync data

  4. In Android, touch Settings to make the settings buttons appear and click the Reset Sync data button.

  5. Import or sync your contacts back to your Android device

Main Screen and Menu

On this screen, you will see a Sync button and a status message below the button. Press the Sync button to start a sync operation. If there were any problems with the sync operation, you will get a message in an alert popup, and data causing the problem will not be transferred. Please see the Known Issues for some reasons problems may arise.

For Android 1.5 and 1.6, you will be asked to turn off syncing of Contacts (set in the Android menu Settings>Data synchronization). Please see the Known Issues for the reason why you should do this.

Touch the text Settings below the Sync button to make these settings buttons appear or disappear:

Press the Menu button while on this screen to get these menu options:

  • View Log File: opens the log file. The log file will contain messages about the start, progress, and completion of the last sync operation.

  • About: message about current app version

  • Help: opens this document.

Group/Address Book Sync Settings

This screen will list your current Contact Group/Address Book sync settings. Each shown setting will have the sync type and the name of the group. To add a setting, select the Add button at the bottom of the screen. You will be given a list of available groups/address books. After you select a group/address book, you can select the type of sync:

  • Import: transfer Thunderbird Address Book to the Android device. This will transfer all data of the selected address book and overwrite similar data on the Android device.

  • Export: transfer the Android Contact Group to Thunderbird. This will transfer all data of the selected group and overwrite similar data in Thunderbird.

  • Sync: transfer between Thunderbird and the Android device. Only contacts that have changed since the last sync will be transferred.

The list of available groups is updated with each Sync operation, so any address books added to Thunderbird after a Sync operation will not appear until after the next Sync operation is done.

To Edit or Delete a setting, highlight then long click on the setting.

Because the Import and Export operations overwrite data, they will have the least problems. If you have problems with a Sync operation, you may be able to work around it by changing to an Import or Export setting. For example, if a Sync operation results in a message about conflicting data and you know the most recent data is on the Android device, you can the change the sync setting to Export to overwrite the Thunderbird data.

Connection Settings

This screen lets you enter the data to connect to the machine running Thunderbird. You can enter the name or IP address of the machine in the top box, and the communication port number in the box below it.

If you use a machine name and it fails to connect, you should try using an IP address instead. Unless you have specific reasons, you should leave the port number alone. But if you change the port number, be sure to make the same change in the Thunderbird extension (select Tools>Add-Ons>Extensions>Android Contacts Sync>Options). You'll need to restart Thunderbird for the port change.

Checking Scan for Thunderbird will cause the app to try a range of IP addresses. The range is defined in the box below the checkbox. This feature is currently configured for IPv4 addresses. The app attempts to connect to addresses described by replacing “*” in the range with values from 0 to 255. The default entry is based on the current IP address of the device. Edit this entry according to your network settings. Depending on the number of addresses the app has to try, the app may take from several seconds to a couple of minutes to find Thunderbird. TIP: if you know the specific IP address range your router uses, you can use a filter like* so that the scan finds your Thunderbird machine faster.

Enter your personal key code in the bottom box. This is used to encode the data transmitted across the network as a security feature. Your key code must be at least 6 characters long. This key code must match the key code in the Thunderbird extension. In Thunderbird, select Tools>Add-Ons>Extensions>Android Contacts Sync>Options to enter the key code.

Reset Android Contacts Sync data

This resets the app's internal sync data. This does not affect the data in contacts. This should only be used if you are experiencing problems.

Allow Any Group Sync

This setting only applies to Android 2.0+ devices. Check this setting and any contact group on the phone will be available to sync with Thunderbird. Without this enabled, only phone-only groups will be displayed as available to the app. If you enable this option, you will be asked to turn off syncing of Contacts (set in the Android main menu Settings>Accounts & sync). This is recommended because this app was written assuming no other application would try to sync with the contacts and modifies the contacts in a way that bypasses normal synchronization. If you have the automatic sync setting on and use this app, updates from an online sync will not be forwarded to Thunderbird.

Be aware that this option will not change the account associated with the contacts. If you would like to make your contacts data private between Thunderbird and Android, follow the instructions in the Updating section, then you will not need to enable the Allow Any Group Sync option afterward.

Known Issues and FAQs

Why can’t I sync over a USB cable?

Prior to Android 2.3.4, there was no official API for communication over a USB connection. Yes, Android has USB communication built into it and other apps have found ways to use it. But since this is not officially open to apps, it could be changed at any time and, of course, break the apps using USB.

Problems connecting

If you provide a machine name for the destination connection, the ability to resolve this name to an IP address is completely dependent on your network/router. I, personally, haven't had much luck with this (I get an IP address that looked like garbage for a machine on my LAN) because of NAT features common on most routers.

Also, check that your firewall software isn't blocking the port number you are using.

If the Thunderbird Error Console has a message about unexpected input, check that the key code is the same in the Thunderbird extension and the Android app.

Android 2.0+: I can't sync my groups (they don't appear in the list to add in Sync Settings).

When you create contacts and groups, they are associated with an account. It is likely all your current groups and contacts are associated with a Google account (the account you signed in when you first started your device). You can use the Allow Any Group Sync option to make these available to the app (see the option instructions for details and limitations).

Android 2.0+: I can't make phone-only contacts on my phone.

This all depends on the contact editor you use. Most contact editors will default to assigning contacts you create to your registered account(s). Either use a contact editor that allows you to make phone only contacts, or create your contacts in Thunderbird and import them (you can still edit these contacts on your device and they'll remain phone only).

Some information isn't synchronized.

The following data are currently not supported for synchronization by this app:

  • Thunderbird custom fields

  • Photos

Only 2 email addresses can be synced to Thunderbird. For Android 2.0+, only 1 IM screen name and 1 Nickname can be synced to Thunderbird. Only 2 web pages can be synced to Thunderbird, the 1st for work and 2nd for home/private.

Sync interrupted.

If you see a message in the log file saying "Sync interrupted:", the likely cause is that the sync operation crashed. If you get this error, you should exit the app (it may not run properly because of the crashed sync process). Also, it's likely the last contact transferred is incomplete.

Android 2.0+: all Thunderbird contacts disappeared from the device.

You will need to turn off the automatic online contacts synchronization (set in the Android main menu Settings>Accounts & sync). I have personally seen the Google sync adapter "hijack" my contacts. The contacts were changed so that they were assigned to my Google account, and then, they were deleted when the phone did a background sync. Of course, this means you will be able to sync contacts only with Thunderbird.

Name fields in Thunderbird have data you didn't enter.

This is because of some unexpected behavior in Android contacts. If you enter a Display name in a Thunderbird contact, when that contact is transferred to Android, Android will copy the Display name to another name field if they are empty.

Synchronization problems for Android 1.5 and 1.6

Because of a bug in Android OS 1.5 and 1.6, the flags that mark contacts with changes that need synchronization cannot be reset outside of the usual data synchronization methods. Consequently, to this app, all contact data always appears to have been modified since the last sync. So, the Sync setting will often have problems: all contact data is transferred from the Android device to Thunderbird every time a sync operation is performed, and changed data from Thunderbird Address Books will always conflict with the Android Contacts. This issue was fixed with Android 2.0 (in other words, you'll need to upgrade your version of Android to make this problem go away).

Android 1.5 and 1.6: why you should turn off Android Contacts synchronization.

This is assuming that you do not want your contacts uploaded to your Google account. If so, in the Android main menu Settings>Data synchronization, you should turn off Contacts synchronization. Under Android 1.5 and 1.6, if Contacts synchronization is on, any contacts created on the phone will be uploaded to your Google account, even if you turned off the Synch all contacts option in the Contacts app. Groups you create may not show up on your Google Contacts, but the Contacts on your phone will still show up under All Contacts. So, unfortunately, Android 1.5 and 1.6 users really only have two options: have all their phone contacts sync to their Google account, or none of them.

Android 2.0+ users should not have this issue. This app will only create and sync "phone-only" contact data (the contact data are not associated to an online account). So, 2.0+ users can maintain online and phone-only contacts on their device.

Synchronization cannot merge changes

For the situation where a contact has been edited both in Thunderbird and on the Android device, it is not possible to determine what parts of the contact have been edited most recently. So, the app will complain about mismatches and not overwrite the data. You will have to manually resolve the differences between the contacts.

Synchronization does not delete contact groups

The app does not detect that a contact group has been deleted. To remove a group, you will have to manually remove it both from your Android device and your Thunderbird Address Book.

The connection is not secure

The Thunderbird extension opens a port to listen for the app (your firewall may warn you of this). This app uses an TCP socket for communication. Your data will be encoded before it is sent across the network. While the data should not be human-readable, the encoding is very basic. I chose not to spend much effort in the encoding because the Thunderbird extension is in Javascript, so the source code is readily available. This may sound paranoid, but if you weren't a little paranoid about your data, you probably wouldn't use this app. This is not an issue if you use a secured LAN.

Postal address data may not transfer as expected

For Android 1.5 and 1.6, postal addresses are each stored as a single text string. In contrast, Thunderbird uses several fields for postal addresses (e.g., street, city, state). When exporting data to Thunderbird, the Thunderbird extension may try to make a guess at which fields that data should go into, but of course, it is likely to do this wrong. It will more likely guess correctly if you format the address on multiple lines, as you would on a piece of mail (e.g. street, city and state on two lines).

I recommend that, after exporting data to Thunderbird,

  1. you inspect the postal address in Thunderbird

  2. move data to the appropriate boxes

  3. import the address book back to your Android device

This will format the address in a manner that the Thunderbird extension expects.

For Android 2.0+ users, contacts have been enhanced and postal addresses are stored in fields that more directly match the Thunderbird fields, so there is far less likely to be problems.

Can this app sync the calendar with Thunderbird Lightning?

No. The contacts database support is part of Android. The calendar is not.


This app is provided "AS IS" and is used at your sole risk. The author of this app disclaims all warranties and conditions of any kind, whether express or implied, including, but not limited to the implied warranties and conditions of data or network integrity, and non-infringement.