gContactSync Frequently Asked Questions (FAQs)
What is gContactSync?
gContactSync is an add-on that synchronizes contacts between Google (Gmail)
and an Address Book in Thunderbird.
You can synchronize multiple accounts with multiple address books, and it
fully supports regular and hosted Google Accounts.
Click on a section to show or hide its contents.
Warning: Please backup your contacts before using gContactSync.
Which applications does it support?
Why doesn't gContactSync work in Thunderbird 60?
Where can I download it?
Why do some of my contacts have strange nobody...@nowhere.invalid e-mail addresses?
Thunderbird does not allow contacts without e-mail addresses in mailing lists, so in order to sync groups with mailing lists, gContactSync adds a fake e-mail address to that contact in Thunderbird only. These fake e-mail addresses will never be added to Google. It is ugly, but the alternative is having a broken, unsynchronizable address book.
There are two ways to avoid seeing these e-mail addresses:
- Version 3.0 and later: when setting up an address book to sync check Skip contacts without e-mail addresses. If you already set up this address book you can go to gContactSync -> Edit Accounts, select your AB, and check the box.
- Do not synchronize groups with mailing lists. Either choose All Contacts (No Groups) or a single group to sync with each address book.
I filed Bug 492695 for the bug in Thunderbird.
Why do I get an error saying cookies are disabled?
The OAuth2 method of authentication that gContactSync uses requires cookies to be enabled for google.com. gContactSync uses a browser window in Thunderbird, so you need to enable cookies in Thunderbird, not your web browser:
- Go to Menu -> Options -> Options (or Preferences, depending on your OS)
- Click on the Privacy tab.
- There are two options now:
- It's easiest to allow cookies from any site. To do this, make sure Accept cookies from sites is selected.
- Otherwise, click on Exceptions, type google.com and click either Allow or Allow for Session, then click Close
Why do I see an error about being offline when I'm online?
This is usually caused by security software (Kaspersky Internet Security in particular) blocking the HTTPS request that gContactSync sends,
or by Thunderbird being in offline mode.
Please see this blog post for more instructions.
Why do I see a 403 error when trying to login?
To debug this issue you will need to look at the log for more information. Go to the gContactSync menu and click on Log. Copy and paste into a text editor (such as Notepad or Microsoft Word in Windows) and search for ERROR: Authentication Error. Find the detailed error message that follows the text Info= and follow the detailed instructions below.
WebLoginRequired
This error means that Google blocked your login because it thinks you aren't who you say you are. This commonly happens if you recently had a few failed login attempts or you are signing in from a different location than normal. There are two options:- Use the beta of version 2.0.0, which uses Google's preferred method of authentication called OAuth2. This will likely show you a captcha image to verify that you are a human. It's perfectly safe to try version 2 and go back to version 1.1.2 if it doesn't work. If you want to try it go here and scroll down to Development Channel.
- Go here, sign in, and fill out the captcha, then try to login with gContactSync again.
InvalidSecondFactor
This means that you have 2-step verification enabled. Again, there are two options:- Use the beta of version 2.0.0, which uses Google's preferred method of authentication called OAuth2. This will likely show you a captcha image to verify that you are a human. It's perfectly safe to try version 2 and go back to version 1.1.2 if it doesn't work. If you want to try it go here and scroll down to Development Channel.
- You may use Google's 2-step verification to add additional security to your Google Account. Doing so lets you generate an application-specific password that you use once with gContactSync.
What happened to phone numbers? Why don't the phone columns match between the top and bottom half of the address book?
gContactSync ignores the actual names of the phone number fields in Thunderbird and instead adds types (Work, Home, Mobile, etc) to make it match Gmail, and improve the address book IMO.
You may also have noticed the new phone number types added by the pre-existing phone number fields when you edit (and create in TB 3) contacts. However, different phone number fields can now be of multiple types (Home, Work, Mobile, etc.) so it is impossible to accurately label a column. Please see this blog post for a more detailed explanation.
You can turn this feature off in Version 0.3 by checking Add phone number type fields... under the Interface tab
Why do I get an "Unresponsive Script" error?
Some people have reported an "Unresponsive Script" error while gContactSync is synchronizing a large address book.
That message appears when some JavaScript (the language in which gContactSync is written) has been running for a certain amount of time as a precaution. I have never managed to get stuck in an infinite loop with gContactSync (which is what this dialog allows you to break out of), so it is safe to click Continue.
If you want to stop receiving these messages you can do the following:
- Go to gContactSync -> Preferences
- Next, go to the Advanced tab
- Enter a higher number under 'Unresponsive Script' warning delay time. You can enter 0 if you never want to see that message, but that also prevents the dialog from appearing when it actually should.
Why do some contacts get updated when I haven't changed them?
Thunderbird keeps track of the number of times you have received or sent e-mail to a certain contact, so gContactSync sees that the contact has changed and updates it.
Why can't I see the 10 extra properties I added in Gmail?
This tab in the preferences dialog is for fields that gContactSync should sync
with other Thunderbird clients. These fields are not visible in Gmail; only
gContactSync sees these fields and knows what to do with them. The names must
be valid fields in Thunderbird.
It's main purpose is for users who synchronize a single Gmail account across several
computers (such as businesses who synchronize business contacts to their employees'
PCs).
This tab is going to be removed in version 0.4 starting with 0.4.0a3. The feature will
still be there; it will just require editing preferences in the Config Editor to change
the fields that are synchronized.
Why doesn't drag and drop work to mailing lists?
Mailing lists are buggy in Thunderbird (check the forum if you don't believe me) and drag and drop doesn't work well to mailing lists. I also modify the drag and drop method to copy over extra attributes that gContactSync adds. gContactSync tries to fix drag and drop as much as it can, but it can still be broken if you try.
How can I add contacts to my address book without drag and drop?
You can copy the contacts to your main address book without many problems. Once they are in there, synchronize. The best way to get them into individual groups is through Gmail, although you can try using Thunderbird.
Can I synchronize multiple address books?
This feature has been possible since version 0.3. Go to the gContactSync menu and click New Account Wizard or Edit Accounts.
Why does gContactSync always say "Synchronizing..."?
There was probably an error during the synchronization. Every error I have seen recently has been relating to mailing lists. Unfortunately, when a mailing list is broken you must 'reset' that address book. Read the two previous questions for why mailing lists might break.
You should also enable verbose logging (see Troubleshooting gContactSync) and check the log.
Where did the sync button go?
gContactSync used to add a Sync button to the address book toolbar by default in versions 0.1 and 0.2, but I turned this off by default in 0.3. If you want the Sync button in the Address Book toolbar and/or the toolbar in the main window, just go to View -> Toolbars -> Customize... and drag the button where you want it.
I sure would like the convenience of the automatic contact sync, but adding my gmail login credentials to this (or any) plugin makes me uneasy. How can I be sure this is secure?
gContactSync is completely open source, so anyone who knows JavaScript can view the source and check if it is secure. It was reviewed by a Mozilla Add-ons reviewer.
You may use Google's 2-step verification to add additional security to your Google Account. Doing so lets you generate an application-specific password that you use once with gContactSync.
gContactSync asks for your username and password so it can send them (securely, more info later) to Google and trade it for a token that will allow access to your contacts without gContactSync needing to store your password for future use (see Google's documentation). After the username and password are traded for the token, gContactSync discards the password. If anything happens to that token then gContactSync asks you for the password again.
In any case, extensions have access to the login manager which stores your credentials for e-mail accounts. If you have a master password then you are prompted to enter it before an extension can access the login manager. gContactSync uses the login manager to store only the authentication token.
Whenever gContactSync sends anything to Google, it is encrypted with TLS/SSL to prevent eavesdropping. You can verify this with a tool called Wireshark.
Why does the summary show a different number of deleted contacts than what I was asked to confirm?
The confirmation dialog that asks permission before deleting X contacts is shown for each account. So it may delete X contacts from account 1, which it asks you to confirm, and Y contacts from account 2, which may not meet the threshold for asking permission. The displayed number of deleted/added/updated contacts is the sum for all accounts. The log has a summary for each account.
I use 2-step verification on my Google Account, can I still use gContactSync? (InvalidSectorFactor in the log)
Version 2.0 supports 2-step verification. With earlier versions you will need to generate an application-specific password to use with gContactSync. See this article for more details.
Why aren't postal addresses synchronized?
Postal address synchronization is disabled by default due to differences in
the way Thunderbird and Google store addresses. Thunderbird stores what are
know as structured addresses, which are the individual components of an
address (street, city, state, zip code, country, etc.) while Gmail stores a
formatted address which contains the entire address in a single field.
Google now automatically converts addresses between these two formats, but it
did not when version 0.3 was released, so I turned it off by default. Version 0.4
has it on by default.
To change the preference and synchronize postal addreses:
- Go to gContactSync -> Preferences
- Click on Advanced
- Check Synchronize postal addreses (EXPERIMENTAL)
Once you change the postal addresses preference you have to update your contacts from whatever source you wish to get the addresses from. Try updating a single contact in the location (TB or Google) with the postal addresses then sync and see if the address is synchronized correctly. If that works, then right-click the synchronized address book and click on one and only one of the following:
- Replace from server (if your postal address are in Google)
- Replace to server (if your postal addresses are in Thunderbird)
I like gContactSync but don't know how to program, can I help?
Absolutely. It is a completely open source project and I'll gladly accept any kind of help:
- Helping people on the forum.
- Finding and reporting bugs.
- Creating icons
- addons.mozilla.org has a "Contribution" program that allows you to donate. Any and all donations are appreciated, but I still provide equal support to everyone (in my free time, usually in order of severity and then in order of reception).
When will birthdays, nicknames, websites and photos be synchronized?
Version 0.4 and later synchronizes all recently added fields in both Thunderbird and
Google. This includes birthdays, websites, nicknames, and photos.
Why do I see a message saying "One or more of your mailing lists has broken"?
This either means that you have encountered a Thunderbird bug with mailing lists or you deleted one of the system groups that Google does not allow you to delete (Family, Friends, Coworkers, and My Contacts). To fix this:
- Right-click on the address book and click "Reset (replace from server)"
- Read the message and click OK.
- Restart Thunderbird, making sure you close every window. There's a nasty bug in Thunderbird if you try to use an address book after deleting a mailing list
- Synchronize.
Why can't I login?
Please see this blog post for tips on fixing authentication errors.
Which attributes/fields are synchronized?
Google* |
Thunderbird |
|---|---|
| Name | Display Name |
| First Name, Last Name, Phonetic Name | First Name, Last Name, Phonetic Name |
| Nickname | Nickname |
| The first two Email Addresses | Primary and Second(ary) Email Addresses |
| The next 2 email addresses | Third and Fourth Addresses |
| The first seven phone numbers | First - Seventh phone numbers** |
| The first instant messaging screenname | Screennames |
| The next five screennames | Additional Screennames** |
| Company | Organization |
| Department | Department |
| (Work) Title | Work Title |
| Notes | Notes |
| Birthday | Birthday |
| Relationship | People** |
| The first URL | Web Page (Private) |
| The second URL | Web Page (Work) |
| Home and Work Address | Home and Work Address*** |
| Other Address | Other Address (multiple lines allowed)** |
*Only the first (primary) attribute of each type is synced from Google unless otherwise noted. The others are preserved while updating a contact.
**The attributes marked with ** are not standard in Thunderbird and are added by this extension to the Address Book.
gContactSync is not able to synchronize the custom fields in Gmail and Thunderbird together due to limitations in Google's API.
All local data that is not synchronized (for example, extra e-mail addresses in a Google Contact) is preserved.