Importing, exporting and moving

Module 7: Your address book · Reading time: 9 minutes

Learning objective: After this lesson you can move your contacts to and from the webmail as a file, you choose consciously between vCard and CSV, and you avoid duplicates and lost groups.

Key concepts: vCard (.vcf), CSV, field mapping, group assignment (CATEGORIES), duplicates, Replace the entire address book, backup, CardDAV

Your address book doesn't move with you automatically

When you move your email from one provider to another, your messages and folders usually come along: they're on the IMAP server and a migration tool copies them. Your address book is stored somewhere else. In the webmail it's a separate list that belongs to the webmail, not to your mailbox. So moving your email doesn't take it along. The same applies the other way round: if you switch from Gmail or Outlook to a new mailbox, your contacts stay behind until you bring them yourself.

You bring them with a file. You export from the old program, you get a file, and you import that file into the new one. There are two types of file you'll come across often.

vCard: the business card

A vCard is a text file with the extension .vcf. Each card starts with BEGIN:VCARD and ends with END:VCARD. In between, each line holds one piece of information, with a fixed name in front of it. This is what a card for Ahmed looks like:

BEGIN:VCARD
VERSION:3.0
FN:Ahmed Benali
N:Benali;Ahmed;;;
EMAIL;TYPE=INTERNET:ahmed@example.net
ORG:Example Groothandel
TEL;TYPE=WORK:+31 20 123 4567
CATEGORIES:Klanten
END:VCARD

• VERSION says which version of the format it is. Version 4.0 is described in RFC 6350; version 3.0 is older, but almost every program still uses and reads it. The webmail exports in version 3.0.
• FN is the full name as you see it, N is the name in parts (surname, first name).
• EMAIL, TEL and ORG speak for themselves. A card can have more than one address and number.
• CATEGORIES is the line for groups. If Ahmed is in your group "Klanten" (customers), the webmail puts that here when exporting.

One .vcf file can contain a single card or hundreds in a row. The advantage of vCard: the meaning of each field is fixed. A program doesn't have to guess what a phone number is.

CSV: a table without agreements

CSV (comma-separated values) is a table as text: the first line contains column names, and each following line is one person, with commas or semicolons in between. You can open it in a spreadsheet. That's handy for tidying up a list, but there's a drawback: there's no fixed agreement about the columns. Google names a column differently from Outlook, and a Dutch-language Outlook differs again from an English one.

That's why, with a CSV file, the webmail has to map the columns to its own fields. If it doesn't recognise a column, it asks you which column belongs to which field. Check that mapping carefully. A classic mistake: the column with the work address isn't mapped, and you end up with a hundred contacts without an email address.

Two more pitfalls with CSV:

• Strange characters. If you see "Müller" instead of "Müller" after importing, the file wasn't saved in UTF-8. Save it again in your spreadsheet as CSV in UTF-8 and import it again.
• Separator. A Dutch spreadsheet often uses the semicolon. If everything ends up in one column, the program read the separator wrongly.

If you have the choice, choose vCard. Google Contacts, Outlook and Apple Contacts can all export as vCard or as CSV.

Importing without damage

Under Contacts > Import you choose the file. Below it are two options that make the difference between a clean import and a messy address book.

Import group assignments determines what the webmail does with the groups from the file (the CATEGORIES lines):

Replace the entire address book first deletes everything that's there and then puts the contents of the file in its place. That's only right if the file really contains everything you want to keep. Leave it off by default.

And what about duplicates? If there's already a contact with the same email address and the same name, the webmail skips it during the import. If the name is written differently ("Ahmed Benali" versus "A. Benali"), it doesn't recognise it as a duplicate and the person ends up in there twice. So if you accidentally import the same file twice, it's not too bad. If you import from two sources with different spellings, tidy up afterwards.

An example. Sanne is switching from an old email program. She exports her contacts there as vCard, 212 cards. She imports with "All (create groups if necessary)" and leaves "Replace the entire address book" off. Afterwards she sees her old groups "Klanten" and "Leveranciers" (customers and suppliers) again, and she searches for a few names she had in both programs, to remove duplicates.

If you receive a business card as an attachment in an email, you don't have to save it first: for a .vcf attachment, the webmail shows a button to add it to your address book.

Exporting as a backup

You export under Contacts > Export. You get one .vcf file with all your contacts; with the arrow next to it you choose between Export all and Export selected (only the selected ones). If your contacts are in groups, those are in the file as CATEGORIES. Open the file in a text editor and check it: if you see the group names, they'll come along again when you import.

An export is also your backup. Your email is on the server and the server makes backups, but you can wipe your address book with one wrong click on Replace the entire address book. Exporting a few times a year and keeping the file in a safe place takes a minute. Do keep in mind: such a file contains personal data. Don't leave it lying around in your Downloads folder or in a shared folder.

The address book on your phone is a different address book

The contacts on your phone and the address book in the webmail are two separate lists. A new contact on your phone doesn't automatically appear in the webmail, and vice versa. Your email program only fetches your email with IMAP, not your contacts.

If you want one address book on all your devices, you need CardDAV: a standard for synchronising contacts between a server and your devices. Nextcloud can do this, for example, and phones and email programs support it. The WebOké webmail doesn't synchronise with CardDAV; there you use importing and exporting. So choose one place as your source of truth, and take an export from there now and then.

In practice: how it works in the webmail

Import and Export are at the top under Contacts. An import can be a .vcf or CSV file. The step-by-step guide is in the Roundcube manual (8.3). Other webmail works in a similar way: Gmail and Outlook.com also have importing and exporting for their contacts, usually with the same two file types.

Summary

• Your address book doesn't move along automatically when you move your email: take it with you using an export and an import.
• vCard (.vcf) has fixed fields and groups as CATEGORIES; CSV is a table whose columns you have to map.
• Leave Replace the entire address book off, and for groups choose consciously between None, All or Only for existing groups.
• The webmail only recognises duplicates with the same address and the same name; tidy up after an import.
• An export is your backup and contains personal data; the address book on your phone is a different list.

Quiz

Exercise

Exercise A7.2: Have your address book checked. Export your address book in the webmail (Contacts > Export; you get a .vcf file) and upload it. If you don't have many contacts yet, create at least three first and put at least one of them in a group. The program only reads the file in memory and stores nothing. It checks: there are at least 3 cards; the version is 3.0 or 4.0; each card has a name (FN) and an email address; there are no duplicates (the same email address on two cards); and there's at least one group (CATEGORIES, otherwise orange). You only see counts, such as "24 cards, 2 without email address, 1 duplicate", never names or addresses. Green if everything is correct; orange if the group is missing, if there are cards without a name or email address, or if there are duplicates; red if there are fewer than 3 cards or the version is unknown.

Further reading

Where steps in the webmail are given, they apply to the WebOké webmail; other webmail works in a similar way.

• Roundcube Webmail 8.3: Importing and exporting contacts
• Roundcube Webmail 8.2: Creating groups
• Restore mailbox or deleted emails from the backup
• RFC 6350, vCard Format Specification (English): https://www.rfc-editor.org/rfc/rfc6350