Upgrading a computer also includes migrating your email. In my case that means migrating KMail, the email client embedded in KDE’s PIM suite Kontact. I have done that before and it was pretty straightforward: just copy the mailbox backup to the new mailbox folder and do a fresh setup of email accounts. This time it should have been even simpler, using the built-in export/import tool. Alas! ‘Twas not to be.
So let me share my misery and forewarn others.
How it should have been
In KMail go to Tools > Import/Export KMail Data…. The PIM Settings Exporter will open. Then go to File > Export Data… and follow the instructions to backup anything you select to where you want to save it.
Two notes.
First: if you use CalDAV or CardDAV for your calendar and contacts, there is no need to backup. Just setup new accounts and everything will be there again.
Second: if you want to copy the email backup to a USB stick, make sure it is formatted with ext3 or ext4 (and not with fat32); see this warning.
Then, on the new system, open Kontact and start the PIM Settings Exporter, go to File > Import Data… and follow the instructions. Done!
And this was exactly what I did. But what was actually done?
How it actually worked
Restoring the KMail backup just created a mess. Email accounts did not work, or could not be found. The mail messages seemed to have disappeared. Folders had been created all over the /home directory. And so on. When I finally found the restored folder with messages, it turned out all tmp folders had been skipped when the backup was made, effectively disabling the mail folders. KMail uses the maildir format for keeping messages and every folder or subfolder must contain three folders: cur, new and tmp.
Uncanny conclusion: this wonderful PIM Settings Exporter just does not know what it does, forgetting to include required folders, restoring to the wrong places, and probably making some more mistakes. And I appear not to be the only victim of failed migrations, since KDE cheers me up with this full page: ‘Clean start after a failed migration‘…
BTW, the information given in the KMail FAQ is outdated. KDE5 stores Akonadi entries in different places (i.e. ~/.config and ~/.local/share/akonadi*), while the semantic indexer Nepomuk has been deprecated in favour of Baloo. (Akonadi is the PIM storage service for Kontact.) Email messages used to be kept in ~/.local/share/local-mail by KDE4, but KDE5 stores these in the (twice hidden) folder ~/.local/share/.local-mail.directory.
What to do next time
So next time I will do it as follows. After clearing up the mess of misconfigured accounts, lost or duplicated folders and more, this was what I basically fell back to this time too.
- Copy the full contents of the mail folder to a USB stick, or an existing partition that is going to be used again.
- Forget about all of Akonadi, Baloo or account settings.
- Start Kontact and make a fresh setup for email accounts and identities, plus contacts, calendar and whatever I use.
- Close Kontact completely (File > Quit, or Ctrl+Q) and stop Akonadi (command: akonadictl stop – also look here).
- Copy the backed up email messages to ~/.local/share/.local-mail.directory and restart Kontact (and Akonadi, if it does not do so automatically: akonadictl start).
Just check if all is well, and adjust details like specific folders for identities. That should be it. Job done.
It would be nice though, if the KDE documentation could be updated! Just have a look at the impeccable Evolution documentation, I might suggest.
Migrating to and from KMail and other email clients
Might you want to migrate from KMail to another application, eg. Evolution or Thunderbird, that should be possible. However, first of all make sure you have absolutely backed up all messages in a safe place and do not delete that backup before you are certain all has been migrated correctly.
Between KMail and Thunderbird, Mozilla’s cross-platform email client, messages must be converted from maildir to mbox format. Thunderbird has an ongoing project of also enabling maildir, but currently that is not yet stable. Extensive information can be found here. KMail’s information is pretty outdated, but perhaps there is still something useful left. Look here.
Between KMail and Evolution, GNOME’s default PIM application, things are similar, since Evolution also uses the maildir format. For information look here, or search the Evolution user documentation.
Migrating to or from Microsoft mail applications, eg. Outlook or Windows Mail, is generally a nightmare if you are not a trained hacker yourself. Microsoft uses the mbox format, but loves to tweak it without telling you how. But if you are in the mood for an extended suffering, do try to find your way with this.