With Debian 8 "Jessie", the Kontact Personal Information Management system receives a major upgrade. The new version makes much greater use of the indexing technologies that have been developed by the KDE community in recent years. For example,

Log out before upgrading

It is highly recommended that the user not be logged into a Plasma desktop session while the upgrade and dist-upgrade is run. At the very least, ensure that akonadi, nepomuk, kmail and kontact are not running.

Email (kmail)

Once the upgrade of the packages installed on the system is completed (that is, after the apt-get dist-upgrade step is finished and the system is booted into the updated kernel as per the release notes, each user needs to migrate their settings from the old kmail into the new.

Troubleshooting:

Email Indexing

If the Message Search facility does not return results, it may be that indexing is not set up properly. Right clicking on an email folder in the KMail folder hierarchy, select Folder Properties → Maintenance and double check that Indexing is enabled for the folder. If all folders show that indexing is enabled but that the folder is not yet indexed, then baloo is not installed and running.

Email Filters

Email filters are not automatically migrated to the new KMail; however, they are not lost. The filters are still all stored in the old kmailrc configuration file and that can be directly imported into the new KMail. (It is also possible to export the filters from Wheezy's KMail prior to the upgrade and the import this backup into the new KMail which is perhaps a little more elegant.)

Custom Email Templates

Custom templates for replying to mails are not imported into the new KMail; however, they are not lost. The templates are still in the kmailrc configuration file.

[CTemplates #Generic thanks]
Content=Dear %OFROMNAME,\n\nThank you for your enquiry. We're sure you'll love the new KMail\nregards\nDebian Qt/KDE Team\n%SIGNATURE
Type=1

echo -en '[TemplateParser]\nCustomTemplates=' >> .kde/share/config/kmail2rc
sed -nr 's/.CTemplates #(.*)]/\1/p' .kde/share/config/kmailrc | tr '\n' , >> .kde/share/config/kmail2rc

This would generate a section in the configuration file looking like

[TemplateParser]
CustomTemplates=Generic thanks,Some template name,

Unresolved KMail Problems

Sent or received?: KMail can get confused about whether a folder is for incoming mail or sent mail (772612) and it is not evident why this is the case. In some circumstances, changing the folders listed in the Identities to not point to subfolders of the Inbox has been reported to help but this is not a universal fix. When KMail gets this wrong, it wrongly shows the Sender or Receiver column in the list of messages and, if it thinks the folder is a sent-mail folder, it may incorrectly show "Edit message" and "Send again" actions in the Message menu and context menu.

Calendars (korganizer)

Calendar data is migrated automatically including local file and directory resources.

Some Google Calendar hosted calenders are not correctly parsed by akonadi and this can result in flashing entries in the calendar, repeated attempts to download the resource and high CPU usage. If authenticated access to the calendar is available, then the new Google Calendars and Tasks akonadi resource is much more flexible. The Google Calendars and Tasks agent can be added from System Settings → Personal Information. Multiple accounts can be configured within this resource.

Addressbooks (kaddressbook)

File based addressbooks are migrated automatically.

For GMail users, the old akondai_googledata_resources (from the akonadi-kde-resource-googledata package) can be replaced with the new Google Contacts resources. These share authentication information with the similarly named Google Calendars and Tasks resources, can configure multiple accounts, understand the tag/categorisation structure of the Google contacts and are much more robust.

Further resources

Userbase:Akonadi Userbase:Akonadi and AddressBook Userbase:Kmail FAQs a little bit outdated