# The &kmail; Handbook

Daniel
Naber

    daniel.naber@t-online.de

David
Rugge

    davidrugge@mindspring.com

2001-09-27
1.03.02
1999
2000
2001
David Rugge

&kmail; is &kde;'s powerful and user friendly email client.

KDE
Mail
email
Client
POP3
IMAP
PGP
GnuPG
GPG

## Introduction

The &kmail; Team welcomes you to &kmail;, a user-friendly mailer for the K Desktop Environment. Our goal is to make a mailer that is beautiful and intuitive without sacrificing power.

If you have never set up an email client on a &UNIX; system before, we suggest that you read through the Getting Started section first so that your setup goes smoothly.

Since most people don't read documentation anyway, here is a collection of the most helpful tips:

- You don't have to use your mouse to use &kmail;. Everything should be possible with keys. &kmail; supports all the standard keys like Tab (switch between panes). The trick is: Left Arrow/Right Arrow always jumps to the previous/next message, but when you hold down &Ctrl;, you can use Left Arrow/Right Arrow to navigate in the Folders pane and up arrow/down arrow to navigate in the Headers pane. Use &Ctrl;Space to select the folder you navigated to.

- In the Composer you can select text and drag it around with the mouse.

- Although &kmail; can be considered reliable you should keep backups of your messages, &ie; just copy the files in `~/Mail` to a safe place.

&kmail;'s homepage is at http://kmail.kde.org, an archive of the developer's mailing list is at lists.kde.org.

Please report bugs in &kmail; using Help Report bug....

We hope you will enjoy &kmail;!

## Getting Started

This is a short introduction to &kmail; and its usage so you can start working with it right away. For more in-depth information see the Using &kmail; section. Note that &kmail;'s installation is described in the appendix.

Invoking &kmail; for the first time creates a directory called `Mail` containing the initial files (`inbox`, `outbox`, `sent-mail`, `trash` and `drafts`) in your home directory. Use Settings Configure &kmail;... to enter some initial information so &kmail; will be able to properly retrieve and send your messages.

The Configure window consists of seven sections: Identity, Network, Appearance, Composer, Mime Headers, Security, and Miscellaneous.

To begin sending and receiving messages you will only have to change the settings in the Identity and Network tabs.

### Setting your Identity

The settings in the Identity tab are fairly straightforward. Fill in the Name field with your full name (&eg; `John Doe`) and the Organization field (optional) with the appropriate information. Next, fill in the Email Address and the Reply-To Address (optional) field with your email address. If you are using PGP or GnuPG you need to set an identity in the PGP User Identity field.

Optionally, set the location of your signature file in the Signature File field. If you want a random signature, you may specify a program and check the The file is a program box.

If you add a new identity, an Add Transport... button will appear (this button does not exist for the Default identity). It allows you to configure a way of sending messages for a specific identity, &eg; you might want to use a different SMTP server for one of your identities.

### Setting up your Account

The Network tab contains the settings that tell &kmail; how to send and receive your email. Many of these settings can vary greatly depending on the setup of your system and on the kind of network that your mail server is located. If you do not know what setting to choose or what to put in a field, consult your Internet Service Provider (ISP) or System Administrator.

#### Sending Mail

The Sending Mail section provides two options for sending messages: sendmail and SMTP. Sendmail has a reputation of being difficult to set up, so if you do not already have a working sendmail configuration, choose SMTP and fill in the Server field with the name and domain of your mail server. You will probably not need to change the Port setting (the default is `25`).

If you do want to use sendmail and you are using a dial-up connection, follow the instructions for setting up sendmail for a dial-up connection in the FAQ section.

The way of sending messages configured here will be used for your default identity and for all other identities that have no own way of sending messages. You can use different ways of sending messages for different identities by adding them with the Add Transport... button in the Identity section.

#### Properties

The Properties section lets you configure how and when messages are sent.

Default send method lets you define what happens when a message is sent. If Send now is selected, the message is sent to the mail server immediately, while if Send later is selected, the message is queued in the outbox to be sent later with the File Send Queued command or automatically when you check your mail, depending on the settings in the Miscellaneous tab.

Message Property lets you select how your message will be encoded when it is sent. Allow 8-bit means that &kmail; will send your message in 8 bit ASCII, which means that all special characters such as accented letters will be sent as-is. If MIME Compliant (Quoted Printable) is selected, special characters will be encoded using standard &MIME; encodings, which may be more portable to other mailing systems than 8-bit ASCII. You normally do not need to change the default.

With Precommand you can specify a command that will be executed before your messages will be sent.

Confirm before send enables a dialog that asks, every time you click Send now, if you really want to send your mail.

#### Incoming Mail

To set up an account so you can receive mail, press the Add... button in the Incoming Mail section. You will then be prompted for the type of account. Most users should select Pop3 or IMAP.

After pressing OK you will be presented with the Add Account window. First, fill in the Name field to name your account. You can choose any name you like. Login, Password, and Host should be filled in with the appropriate information from your ISP or System Administrator. You should not need to change the Port setting (the default for POP3 is `110`, the default for IMAP is `143`).

##### Options only relevant to IMAP

If you are using IMAP, you can optionally specify a path in the Prefix to folders field. This tells &kmail; where it can find your folders on the server. If you also have a shell account on the server and the mails are stored in your home directory it might be useful to store the mails in a subdirectory `/Mail/`. Use this as a value in the Prefix to folders field so that &kmail; does not mix up mailbox files and other files. Note that even with a slash as the first character, this path is interpreted relatively to your home directory. If you are not interested in this feature, simple leave the field blank.

If you check Automatically expunge deleted messages &kmail; removes the mails you deleted from the server as soon as you leave a folder. Otherwise the mails are only marked as deleted and it is up to you to compact the folders manually by using the menu item Compact all folders.

If you check Show hidden folders, folders whose name starts with a dot are also displayed.

##### Options only relevant to POP3

Select Delete mail from server if you don't want to leave your messages on the server after you downloaded it.

Select Exclude from "Check Mail" if you don't want to check this account whenever you use Check mail. You can still check for new messages on this account with File Check Mail in.

Select Enable interval mail checking if you want &kmail; to check for new messages automatically. The interval can be specified below under Check interval (minutes).

inbox is the default folder for incoming mail. If you want to change that for some reason, you can do so with Destination folder. But what you probably want is a filter, which has nothing to do with this option.

With Precommand you can specify any program that &kmail; will execute just before fetching mail. Please specify the full path and note that &kmail; will not continue until the program returns.

##### Options for both IMAP and POP3

If you select Store POP password in configuration file resp. Store IMAP password in configuration file &kmail; will remember your password so you won't have to type it every time you start &kmail; and fetch new mail.

Be warned that we cannot really encrypt your password, so people who can access your configuration files (&eg; system administrators) can easily get your password if you select this option.

&kmail; supports encryption via SSL and TLS (TLS should be preferred if it is available).

For POP3 &kmail; supports Clear text, PLAIN, CRAM-MD5 and APOP authentication. APOP and CRAM-MD5 are secure on their own, all the other options are only secure when used together with SSL or TLS. You should only use Clear text if your server doesn't support any of the other authentication methods. Additionally, for IMAP Anonymous is supported.

You are now ready to send and receive mail! For IMAP, click on the + sign in the folder tree in &kmail;'s main window. &kmail; then connects to your server and displays the folders it finds. For POP3 use File Check Mail.

### Testing your Setup

First, you should send yourself a message to test your configuration. To send a message, hit &Ctrl;N, select the New message icon (the empty sheet of paper) or select the Message New Message... menu item. The Composer window will appear. Fill in the To: field with your email address and type something in the Subject field. Send the message by selecting Message Send now.

To check your email, select File Check Mail. In the lower right corner of the main window, a progress bar will indicate how many messages are being downloaded. If you receive the message you just sent, then congratulations! If, however, you receive any error messages while testing your setup, make sure that your network connection is working and recheck your settings by selecting Settings Configure &kmail;...

## Using &kmail;

### The Main Window

The main window is the window that appears when &kmail; is started. It is divided into three panes:

Folders pane (left pane)

  This pane contains a list of your message folders (other email programs call them mailboxes). If there is a number after the folder name this indicates that this folder contains unread mails. To select a folder, simply click on it. The messages contained in the folder will now appear in the Headers pane. The number of unread messages and the total number of messages in the selected folder is now displayed in the status bar. The folders can be displayed in both a short view, which takes up only a small portion of the left side of the screen, and a long view, which takes up the entire left side of the screen but is able to show more mailboxes. You can toggle between these two views under Appearance/Layout in the Configure &kmail;... dialog. Also see the Folders Section for more information about how to use folders.

Headers pane (upper right pane)

  This pane lists header information (message Status Flags, Sender, Subject, Date, optionally Size and Score) for the messages in the currently selected folder. Clicking on a header will select that message and display it in the Message pane. You can also select a series of messages by clicking on one message, holding down the Shift key, and clicking on another message. The two messages you just clicked on will be selected, along with all the messages in between. By holding down the &Ctrl; key you can select any number of messages without those in between. You may sort the messages by clicking on the column that you wish to sort. If you click on the same column more then once, sort order will toggle between ascending/descending. If you click on the Subject column, you can toggle sorting between Subject ascending/descending and Status ascending/descending. Similarly, if you click on the Date column, you can toggle sorting between Date ascending/descending and Date (Order of Arrival) ascending/descending.

Message pane (lower right pane)

  This pane displays the header and body of the currently selected message. Attachments appear at the bottom of the message. You can scroll through the message page by page using the Page Up and Page down keys, or line by line using the up arrow and down arrow keys. You can also use the following key shortcuts to skip through your messages without having to use the mouse:

  Keyboard Shortcut | Action
  --- | ---
  Space | Scroll down in the current message or go to the next unread message if you are already at the bottom
  Right Arrow or N | Next message in the current folder
  Left Arrow key or P | Previous message in the current folder
  + | Next unread message in the current folder
  - | Previous unread message in the current folder
  &Ctrl;+ | Go to next folder with unread messages
  &Ctrl;- | Go to the previous folder with unread messages

Messages can have one (not more) of several status flags, which can be changed from the Message Set Status submenu. The status flags are described below:

Status | Symbol | Meaning
--- | --- | ---
New | Red dot | The message has been received for the first time, and is unread.
Unread | Green dot | The message has already been retrieved off the server at least once, but has not yet been read.
Read | Dash | The message has been read
Replied | Blue u-turn arrow | A reply has been composed to this message.
Queued | Envelope | The message has been queued in the outbox to be sent later.
Sent | Angled envelope | The message has been sent.
Flagged | Flag | This status will not automatically be set by &kmail;. You can use it freely to mark messages that are in some way important to you.

### The Composer Window

The Composer window is used to write new messages. It can be invoked from the Message menu or from the document icon on the Mail Reader window button bar. If you have not set the location of your signature file and you have Use a signature from file checked in the Composer tab of the Configure &kmail;... dialog, you will be prompted for the location of your signature file before the Composer window opens.

#### Composing a Message

To write your message, fill in the appropriate fields in the Composer window. There are a variety of shortcuts to help you with writing your messages. The ellipsis buttons next to the To:, Cc:, and Bcc: fields will call up the address book so that you can select addresses from there.

When you start typing an address in the To:/Cc:/Bcc: fields, a popup will appear that offers matching addresses that have been used recently and matching addresses from your address book. Note that this auto-completion is case-sensitive, so if you type john, John Doe <doe@acme.com> will not show up automatically. If you don't like the automatic popup you can disable it by clicking with the &RMB; on the field and choosing a different completion mode.

Whenever you want to add more than one recipient in one of the fields, use a comma to separate each address from the next one. You may need to specify fully qualified addresses (&ie; `user@domain.com`) even for local users.

You can use the View menu to set up the header fields offered to you. When you are finished with your message, hit the Send button (the envelope) to queue or send the message. If you don't want to send your message yet, select Message Save in drafts folder.

#### Attachments

You can attach files to your message by using one of the methods below:

- Click the paper clip button and select the file you wish to attach.

- Drag a file from the desktop or another directory into the Composer window.

- Select one of the options in the Attach menu.

The Message Part Properties dialog will appear to prompt you for information about your attachment. The &MIME;-type and Name fields are automatically filled in with the appropriate values. Sometimes the &MIME;-type value may be wrong. You can then type in any content &MIME;-type or choose from the list of common &MIME;-types. You can also select an encoding method for your file from the list of encoding options (normally, the default value works fine).

Once a file is attached to your message, it appears in the Attachments pane at the bottom of the Composer window. You may remove, save, or get information about an attachment by selecting its name in the Attachments pane and selecting Remove, Save..., or Properties... from the Attach menu.

PGP/GnuPG keys may also be attached to your message by using the appropriate options in the Attach menu. PGP key attachments are handled like file attachments.

You can encrypt your messages sent with &kmail;, but this does not mean that the attachments are encrypted. You have to encrypt your attachments manually, using a shell command or some other tool before you attach them.

#### Checking the Spelling of your Message

To check the spelling of your message, select Edit Spelling.... &kmail; uses &kspell; to check spelling, which is the &kde; frontend to the ispell or aspell spelling checker. Note that you may need to configure the spellchecker using Settings Spellchecker....

### Message Folders

Message Folders are used to organize your email messages. By default, all message folders are stored in the directory `Mail`, which is created in your home directory. When you first start &kmail; the inbox, outbox, sent-mail, trash and drafts folders are created. These folders each have special functions:

inbox:

  Where &kmail; by default puts your new messages when you ask it to check your mail.

outbox:

  Where messages are put while they are waiting to be delivered.

sent-mail:

  Contains copies of all messages that you have sent.

trash:

  Contains all messages that you have deleted.

drafts:

  Contains messages you started to edit but didn't finish.

You may find that the standard folders are fine for your needs. Eventually, though, you will probably need folders to help you organize your messages. To create a new folder, select Folder Create... A window will then prompt you for the name of the folder. If you don't want it to be a top level folder, you may choose the folder under which it will appear. If you ever need to change the settings for a folder, select the folder you wish to modify in the Folders pane and select Folder Properties... .

To move messages from one folder into another, select the message(s) you want to move and press the M key or select Message Move to. A list of folders will appear. Select the folder from the list that you want to move the messages to. Messages can also be moved by dragging them from the Headers pane into the Folders pane.

If you want to clear all of the messages out of a folder choose Folder Empty. All the messages in the selected folder will be moved to the trash folder. If the selected folder is the trash folder, all of the messages will be permanently deleted.

### The Address Book

An address book lets you store your commonly used email addresses. You can call up the address book from the File menu, the address book button on the Main window, or the address book button in the Composer window.

You can choose between different types of address books in the Appearance/Addressbook section in &kmail;'s Configure &kmail;... dialog.

The default address book is &kaddressbook;, which has its own documentation.

#### &kmail;'s simple traditional address book

To add addresses to the address book, type an email address into the lower section of the window and hit the Add button. The address will then appear on top of the list (the next time you open the address book it will have its place according to the alphabetical order). To remove an address, select it from the list and hit the Remove button.

Addresses can also be added to the address book from the Mail Reader window by &RMB; clicking on an email address in the To: or From: fields and selecting Add to address book.

### Filters

After using &kmail; for a while, you may find that you have trouble sorting out the new messages in your inbox when they arrive. Filters allow you to automatically perform certain actions on incoming messages and to manually perform actions on selected messages in a folder.

Filters consist of a search pattern, whose rules are used as criteria to determine whether this filter should be applied to a given message, and a list of filter actions, which describe what is being done with or to the message if the search pattern matches. Read more about search patterns and filter actions in the following subsections.

Filters are considered one after the other, starting with the first filter in the list. The first one whose pattern matches the given message gets executed. You can request that the remaining filters also be applied, but the default is to stop processing at the first matching filter.

Usually, filters are used on incoming messages, but they can also be applied to a message or a group of messages. To selectively filter messages, select the messages you want to filter and type &Ctrl;J or select Message Apply Filters. This will apply all your filters to those messages; there is no way to apply only certain filters to messages, except for incoming and outgoing messages.

#### Fast Filter Creation

There are two methods for creating a filter: The quick method is to use Message Create Filter. This will call the filter dialog and present you with a new filter which has the first rule of the search pattern and the first action (as move to folder) preset. In most cases, all you have to do is select the folder where the message should be moved to. But you can, of course, edit the filter as you like.

The interesting thing about this method is that creating a filter on mailing lists will try really hard to find a header that uniquely identifies mails from that list. If it succeeds, the guessed name of the list is presented in the Message Create Filter Filter on Mailing-List... menu entry.

In most cases this works very well, yet sometimes you should delete parts of the header contents that are likely to change again. Usually, just keeping the list address works best.

The second method is to manually construct a filter from scratch by calling the filter dialog through Settings Configure Filters.... The filter dialog is described in detail in the following subsection.

#### The Filter Dialog

This dialog allows you to manage and edit your list of filters.

You reach it either via Message Create Filter or Settings Filter Rules....

To exit this dialog without applying changes, click on Cancel or hit &Esc;.

The dialog is divided into four main sections:

Available Filters

  This group contains the list of filters and action buttons to modify the filters, namely to create new filters, to move them up or down the list, or to delete and rename them. If you select a filter from the list, its properties are shown in the right-hand half of the dialog.

Filter Criteria

  In this group you can edit the pattern that messages must match for the filter to be applied to them. You can select here whether all of the defined rules must match or whether it suffices that any one of them matches. See Search Patterns below for a detailed description of each search rule type.

  You can click on More to get an additional (initially empty) rule if you want to define more complex patterns and on Fewer to remove the last rule. Clear clears the pattern, &ie; it removes all but two rules from screen and resets those two.

  Invalid or empty rules are not evaluated. In fact, they are removed internally. Whether a given rule is considered invalid depends on the type of rule, but as a rule of thumb you can assume that rules are considered invalid if the domain (the first combobox in each row) or the search string (the line edit at the end of each row) is empty. Thus, to effectively delete a particular rule, you only need to empty one of those two edit fields.

Filter Actions

  In this group you can edit the list of actions that is applied to all messages that match the defined search pattern. See Filter Actions below for a detailed description of each action type.

  You can click on More to get a new, empty action if you want to define more than one action and on Fewer to remove the last action. Clear clears the list, &ie; it removes all but one action and resets that one.

  Invalid or empty actions are not executed. In fact, they are removed internally. Whether a given action is considered invalid depends on the type of action, but as a rule of thumb you can assume that actions are considered empty if no type is selected or - in case of actions that need a textual parameter (&ie; one which must be entered into a line edit) - the parameter is empty. Thus, to effectively delete a particular action, you only need to unset its type, &ie; select the last (empty) item in the type combo box.

Advanced options

  In this group you can define a few advanced options for filters, that allow you to refine your filtering.

  Using the combo box, you can toggle the applicability of the corresponding filter: The incoming choice shows that it may be considered for incoming mails (&ie; on Check Mail), while the outgoing choice shows the same for outgoing mails (&ie; on Send).

  Note that it is currently not possible to define a filter that is not considered for manual filtering. This is a known limitation.

Filters are automatically named unless you explicitely rename them using the Rename... button. The dialog assumes that it should continue auto-naming the filter as long as the filter name starts with <.

Click on the OK button to apply all changes and close the dialog, Apply to apply all changes and leave the dialog open, and Cancel to close the dialog without applying any changes.

If you apply filter changes, &ie; via OK or Apply, only valid filters are actually copied to the internal filter manager.

A filter is considered invalid if

1. the search pattern contains only empty rules or

2. the action list is empty.

Similarly, empty rules and actions are removed from the pattern and action list respectively, before the filter is saved.

#### Search Patterns

The most common use of filters is to filter on the sender of messages. This can be done by choosing From. A good bet for a mailing list would be <To or Cc>. But there are other criteria a filter can search for:

<message>

  Searches the whole message (&ie; headers, body and attachments, if any).

<body>

  Searches the body of the message.

<any header>

  Searches the headers of the message.

<To or Cc>

  Searches the To and Cc header fields of the message.

<size>

  Sets upper or lower bounds on the message size.

<age in days>

  Sets upper or lower bounds on the message age.

Any other string

  Searches the header field that is given by that string.

#### Filter Action

The most common use of filters is to sort incoming messages to certain folders. This can be done by choosing move to folder. Here's a list of all possible actions:

move to folder

  This will move the message to another folder. You currently cannot use IMAP folders as a target.

mark as

  This allows you to mark the message as read or important (flagged), but also as forwarded, replied, &etc;

set identity to

  This will set your identity if you reply to this message.

set transport to

  This will set the method of transport (&eg; SMTP) if you reply to the message.

set Reply-To to

  Will modify the Reply-To field of this message. This can be useful for mailing lists that automatically set a Reply-To which you don't like.

forward to

  Will forward the message to another email address.

redirect to

  Will redirect the message to another email address.

bounce

  Will try to return the message to the sender as undeliverable.

  This will only work if the senders email address is valid. That's not the case for most spam.

confirm delivery

  Will try to return a message to the sender that indicates successful delivery of his or her message.

  This action allows you to select who will get delivery receipts from you. Though you can enable the sending of delivery confirmations in the Configure &kmail;... dialog (section Security) we recommended to not send them to everyone, since this makes tracking of &eg; spam very easy for the sender.

remove header

  Will remove all header fields with the given name from the message. This is useful mainly for removing bogus Reply-To: headers.

add header

  If no such field is already present, will add a new header field with the given name and value to the message. If there is already a header field with that name, it is overwritten with the new (the given) value. If there are already multiple headers with the given name (&eg; Received: headers), an arbitrary one of them is overwritten and the others are left unchanged. This is a known limitation. You may want to combine this filter with the remove header filter above to make sure that there are no other headers with that name in the message.

rewrite header

  Will scan the given header field, modify its contents and write it back. The search string is always interpreted as a case-sensitive regular expression. The replacement string is inserted literally except for occurrences of `\n`, `$n` and `${nn}`, where `n` is a positive (single-digit, except for the third form) number or `0`. These constructs are interpreted as backreferences to substrings captured with parentheses in the search string.

  Analogous restrictions as in the add header action apply here, too.

execute command

  This will execute a program, but will not modify the message. Specify the full path to the program you want to execute. &kmail; will block until the program returns. You can feed the program with the parts of the mail: &percnt;0, &percnt;1, &etc; will stand for files representing the message parts. For common mails &percnt;0 is the text, &percnt;1 the first attachment and so on. Additionally, the whole message is fed into the program's stdin.

  This currently only works if the message has at least one attachment. No, not even &percnt;0 will work in the general case!

  You can enter arbitrarily complex shell commands here, since &kmail; uses a subshell to execute the command line. Therefore, even this command will work (within its limits): ``uudecode` `-o` `$(mktemp kmail-uudecoded.XXXXXX)` && `echo` `$'\a'``

pipe through

  This will feed the message to a program. If that program returns output, the entire message (including the headers) will be replaced with this output. If the program doesn't return output, the message won't change. Specify the full path to the program.

  Be cautious with this action, as it will easily mess up your messages if the filter program does return garbage or extra lines.

#### Filter Examples

If I am subscribed to the (general) &kde; List, I could create a folder for the list (I'll call it KDE-General) and use a filter to automatically transfer new messages from my inbox to my KDE-General folder if they are from the &kde; List. Here is how to create this filter:

##### Filtering a mailing list

1. Try if Message Create filter Filter on Mailing-List... can identify the mailing list (the name of the list should then appear in the menu item). In this case, this works and I am presented a filter that has X-Mailing-List equals <kde@lists.netcentral.net> preset. You select the desired destination folder from the folder pull-down menu in the Filter Action group and that's it!

   If that does not work, think of a unique way of identifying the messages you want to filter. The (almost) unique property of my &kde; List messages is that they always contain kde@lists.netcentral.net in the To: or Cc: field. It's only almost unique, because this fails for cross-posted messages.

2. Select Settings Filter Rules....

3. Press the New button to create an empty filter. It will appear as <unnamed>.

4. In the Filter Criteria area, select <To: or Cc:> from the first pull-down menu, contains from the second pull-down menu, and type `kde@lists.netcentral.net` in the text field.

5. Skip down to the actions section. Select move to folder from the first pull-down menu. A new pull-down menu containing a list of folders will appear. Select the folder that you want the filtered messages to be transferred to if they match the criteria you selected. For this example, you would select KDE-General from the pull-down menu.

You may find that you need to use more powerful criteria to properly filter your messages. For example, you may only want to filter the &kde; List messages that are written by your friend Fred Johnson <fj@anywhere.com>. This is where the rest of the matching criteria section comes into play:

##### Extending the filter

1. Open up the Configure Filters... window and select the filter you just created.

2. Since you want to filter all messages that have kde@lists.netcentral.net in the To: or Cc: field and that are from Fred, check the Match all of the following radio button.

3. Now, go to the second search rule and select the following from the pull-down menus: From, contains. Now, type `fj@anywhere.com` in the text field.

You now have a filter that transfers all &kde; List messages that are from fj@anywhere.com.

### Multiple Accounts

Multiple accounts are used to check fro messages from more than one email address and/or mail server. Select Settings Configure &kmail;... and click on the Network tab to add or change your account settings. See the Getting started section for more information on the settings in the Network tab.

To check for messages from a particular account, use the File Check Mail in... submenu to select the account to check for mail. You can also press the mouse button on the Check Mail icon for some time to get a list of accounts.

### Pretty Good Privacy (PGP) / GNU Privacy Guard (GnuPG)

This is a short introduction on how to setup &kmail;'s PGP support. It will give some hints on the use of PGP too. It's written for people who are beginners in this area. If you are familiar with the use of PGP, you can skip most of the steps. This documentation (and the &kmail; user interface) generally talks only about PGP, but it applies to both PGP and GnuPG, although some GnuPG command line parameters may be different.

Please also check out the &FAQ; item about PGP.

You can encrypt your messages sent with &kmail;, but this does not mean that the attachments are encrypted. You have to encrypt your attachments manually, using a shell command or some other tool before you attach them.

&kmail; has to rely on PGP's output. This output is often different between different version of PGP, so it's important that you test if encryption really works with your setup before you start using it seriously. &kmail; might not warn you if something fails. You better enable Show ciphered text after composing.

To setup and use PGP support in &kmail; it is necessary to have PGP installed and set up properly. Of course we cannot give you a full introduction of PGP here. We will only mention the steps you have to do to get PGP going. For details you should have a look at the excellent PGP documentation or The GNU Privacy Handbook.

It is certainly a good idea to study this documentation as well as an introduction into public key cryptography (&eg; out of the PGP 6.5.x package). There you can learn a lot about the basic concepts, which will help you to understand what is going on. As well, many security related issues you should know about are discussed there.

Now let's start.

#### Preconditions

&kmail; expects that your PGP binary is called `pgp`. In case of GnuPG, it expects the binary to be called `gpg`. If that's not the case for you, just make a symlink.

If you haven't done so, you have to generate a key pair (secret and public key) for your identity. You must do this at the command line (use ``pgp` `-kg``). &kmail; has no internal support for pgp's key generation at this time. The identity (normally your name followed by your email address within brackets, such as `John Doe <john@example.com>`) and your passphrase are important for the co-operation between &kmail; and pgp.

#### PGP Related Settings in &kmail;

Enter your PGP user identity in the corresponding field of the Identity settings. Then select the PGP tab on the Security settings page. There you' ll find the following options:

Keep passphrase in memory

  When this option is off, &kmail; will ask for your passphrase each time you sign a message (before sending) or select an encrypted message. If you turn this option on, &kmail; will remember your passphrase from after your first successful input until you finish your &kmail; session. The passphrase is stored in memory and not written to the harddisk.

Always encrypt to self

  If this option is off and you want send an encrypted message to somebody, then you can't read this message any longer after you have composed and encrypted it. Turn this option on to keep sent encrypted messages readable for you too.

Show ciphered text after composing

  This will show you the result of encrypting and signing before the message gets sent. This way you can still cancel sending if encrypting failed. It is strongly recommended to use this option.

Encryption tool

  Here you can choose if you want to use PGP, GnuPG or no encryption software at all. Of course the program you select has to be installed on your system. It is also important to select the correct version.

On the Composer tab you can also check the Automatically sign messages using PGP option. This means that all your messages will be signed before being sent. (So you don't have to set the signing option for each message manually.)

Now you are able to sign outgoing messages. To let people send you encrypted messages and to let them verify your signature you must send them your public key or upload your public key to a public PGP key server so that they can fetch your key from there. To send encrypted mails to other people or to verify their signed messages you will need their public keys. You can store your public key(s) on a public PGP key server such as http://www.cam.ac.uk.pgp.net/pgpnet/.

#### Sign your Messages

You compose your message as usual in the Composer window of &kmail;. Before you send the message, check the button with the underlining icon on it in the toolbar of the composer window. Then, you can send the message. To sign it, &kmail; needs to know your PGP passphrase. If you didn't select Keep passphrase in memory in the Security settings tab, &kmail; will ask you for it. On the other hand, if you have already given the phrase to &kmail;, it will sign the message without any further prompt.

#### Send your Public Key

Prepare a message to the person you want to send your public key to. Then choose in the Composer window's menu Attach Attach My Public Key. This will attach your public key to the mail. Now you can send the mail.

Remember that it's not safe at all if you sign the message to make sure that the receiver will get the correct key. There can be a man-in-the-middle attack, as somebody can change the key and sign the message with that other key. That's why the recipient should verify the attached key by checking the key's fingerprint against the one he got in a secure way from you. Have a look at the PGP documentation for further details.

#### You got an encrypted Message

All you have to do is to select the message in &kmail;. You will be prompted for your passphrase. Then &kmail; will try to decrypt the message and show you the plain text if the message had been encrypted with your public key. (If not, then you won't be able to read it.) &kmail; stores the messages encrypted, so nobody can read these messages without knowing your passphrase.

#### Receiving a Public Key

You can receive a public key as an attachment or via http, ftp or a floppy. Before you can use this key to encrypt a message to the owner of the key, you should verify the key (check its fingerprint or look for trusted signatures). Then you can add this key to your public keyring by typing ``pgp` `-ka` filename` at the command line if you are using PGP or by typing ``gpg` `--import` filename` at the command line if you are using GnuPG. If the key is not certified with a trusted signature and you are using PGP, you can't use it with &kmail; to encrypt messages unless you have signed that key (use ``pgp` `-ks` identity of the key`). With GnuPG, on the other hand, it's currently possible to encrypt messages with untrusted keys.

#### Use Public Keys of other People - Encrypt your Messages

To send an encrypted message to somebody of whom you have a public key, you simply create the message in the composer window. Before you send the message, check the button with the lock symbol in the toolbar of the composer window. Then send the message.

&kmail; always uses the first key which matches the recipient's address to encrypt the message. If &kmail; can't find a matching key for a recipient, it will display a list containing all available keys. You can choose the appropriate key from the list or cancel the action. &kmail; might also inform you about errors throughout the encryption process.

As mentioned above, you won't be able to read your own encrypted sent mails if you don't check Always encrypt to self in the setting's Security tab.

## Configure &kmail;

&kmail;'s settings window gives you a number of ways to configure &kmail;.

### Identity Tab

The Identity Tab is described in the Getting Started section.

### Network Tab

The Network Tab is described in the Setting up your Account section.

### Appearance Tab

#### Fonts

This section allows you to change the type, size and character set of the display fonts. Message Body sets the font for both the reader pane and the composer window. There's a separate entry for Message List - Date Field so you can choose a monospaced font for the date field for better readability.

#### Colors

This section allows you to change the color of the text. Recycle colors on deep quoting means that even text that's quoted more than three times will appear in color.

#### Layout

Show long folder list lets you toggle the long folder list on and off. The long folder list shows folders all the way down the left side of the &kmail; main window, which lets you see more folders than in the short view, but it takes away some space for viewing the text of the messages. With Display message sizes selected there will be another column in the Header pane that shows the messages' size in bytes. Thread list of message headers will put all the messages in a kind of tree, so the replies to a message are below that message.

With Message header threading options you can select under which conditions threads should appear open by default (&ie; not collapsed). You can still open/close threads using the +/- buttons if you don't disable that here.

With Display of Date you can choose between several date formats. The Localized Format is the one you can specify in &kcontrol;.

#### Profiles

This section offers several default settings.

#### Addressbook

This section allows you to choose between several address books, whereas Traditional KMail is a very simple one and &kaddressbook; is an advanced one - we recommend to use &kaddressbook;. Note that you need the kdeutils package to use KAB.

While the Traditional KMail database is independent (&ie; you will not see addresses in KAB/&kaddressbook; if you only entered them in the Traditional KMail address book), KAB and &kaddressbook; use the same database.

### Composer Tab

#### General

The Phrases section lets you define the automatically generated lines that are added to message replies, forwarded messages, and quoted text. There are special &percnt;-denoted characters that will insert certain values. These are shown at the top of the Phrases section: %D to insert the date, %S to insert the subject, %F to insert the sender, %% to insert a percent sign, %_ to insert a space, and %L to insert a line break. You can add reply phrases in languages other than your default &kde; language using the Language button. This will only work for languages whose i18n package you have installed.

The Indentation field contains the character that will denote quoted text (you will probably want to use the default).

Automatically append signature lets you toggle whether to automatically include your signature as defined in the identity tab.

Use smart quoting will break long lines but will try to keep the correct quoting (&eg; the > will always be at the start of the line).

Automatically sign messages using PGP lets you toggle whether to automatically sign your messages by default. Of course you can still deselect the icon in the composer window for each message if necessary.

Word wrap at column lets you turn word wrapping on and off in the Composer window and lets you set the column at which words will be wrapped (you probably should not need to change the default value, which is `78`).

#### Editor

If you don't like the Composer you can use a different editor. Note that the Composer window will still open and the external editor will open as soon as you type just one character in the body of the message. If you're done, save the text and exit the editor. The text will now appear in the Composer window, where you can send it.

#### Subject

This section contains a list of prefixes for Reply and Forward. If you receive messages that use prefixes different to the standard ones, you can add them here so &kmail; will recognize them (this way &kmail; can ignore them for sorting messages and optionally replace them).

#### Charset

In the Available charsets section you can manage the charsets available for your own messages. The charsets in this list appear in the composer's Options Set Encoding menu.

The Default charset section lets you choose the default charset for your own messages. If you select Use own default charset when replying or forwarding, the original message's charset will be ignored and your charset will be used for replying and forwarding.

### &MIME; Headers Tab

The Create own Message-Id headers section lets you define how your messages' Message-Id field will be generated. The Message-Id must have a suffix that's world-wide unique. Depeding on your setup, this might already be the case. You should send yourself a message and look at its headers. If it contains a Message-Id that ends in localhost or any other string that's not guaranteed to be unique you need to select Create own Message-Id headers and set a unique suffix. The best thing is to use the name of a domain which you are the owner of.

The Define custom mime header tags section sets the headers that &kmail; will use for its outgoing messages. You can both invent new fields and overwrite existing ones. This feature is only useful for advanced users.

### Security Tab

#### General

Prefer HTML to plain text will show HTML messages with their HTML formatting and layout. We strongly recommend to leave this option off, as security problems with HTML might show up. When this option is off, you can still read HTML messages, but only as plain text.

Load external references from the net will load external images, style sheets &etc; from the internet when you look at an HTML message. We strongly recommend to leave this option off (although it has no effect if Prefer HTML to plain text is off already). By adding external references to their mails, people sending spam can detect that you have looked at their message. Note that this option has no effect on Java, Javascript and Plugins - these are disabled anyway and cannot be enabled at all.

Automatically send receive and read confirmations will automatically send a confirmation (in form of a new message) to the sender of a message if he requested that. If you leave this option off, no confirmation will be sent. We recommend to leave this option off. If you want to send confirmations to certain people you can do so by using the confirm delivery filter action.

#### PGP

For the PGP tab please see the PGP section.

### Miscellaneous Tab

#### Trash folder

Empty trash on exit

  The trash folder is cleared of messages when you quit &kmail; if this option is selected. The following two options are disabled, if this one is enabled.

Keep trash size below...

  On exit, delete old messages if the trash folder becomes bigger than this limit.

In trash, on exit, remove messages older than...

  The trash folder is cleared of messages older than the given age when you quit &kmail;, if this option is selected.

#### Folders

Send Mail in outbox Folder on Check

  All messages queued in the outbox folder will be sent whenever you check for new mail.

Compact all folders on exit

  This will compact all folders every time you exit &kmail;. Compacting folders means that the messages you deleted will really be removed.

Confirm before emptying folders

  To empty a folder means that its messages get transferred to the trash folder (and only get deleted if they are already in the trash folder). So although you normally won't lose any mail, you can still activate a confirmation dialog that will ask you if you really want to empty the folder.

#### New Mail Notification

This let's you configure actions for the arrival of new mail. Note that automatically fetching messages can be configured in your account settings under Incoming Mail.

## Menus and Keyboard Shortcuts

Each menu item is discussed below. When there is a keyboard shortcut that performs a menu item function, it is listed with the menu item.

### The Main Window

#### File Menu

File New Mail Client...

  Creates a new main window.

&Ctrl;S File Save As...

  Saves the currently displayed message to a text file, including all the headers and attachments.

&Ctrl;P File Print...

  Prints the currently displayed message.

File Compact all folders

  Will compact all folders, &ie; it will really move and delete the messages on disk according to how you have moved and deleted them in &kmail;.

&Ctrl;L File Check Mail

  Checks for new messages in all your accounts, except those that have Exclude from "Check Mail" enabled.

File Check Mail in

  Submenu that lets you check for new messages from a particular account.

File Send Queued

  Sends the messages that are in your outbox.

File Address Book...

  Opens up the Address Book.

File Import...

  Starts up kmailcvt (which is part of kdenetwork). This application lets you import messages from several proprietary mail clients to &kmail;.

&Ctrl;W File Close

  Closes the current main window or exits &kmail; if there's only this one window.

#### Edit Menu

&Ctrl;Z Edit Undo

  Revoke you last move or delete action. Note that you cannot undo a deletion in the trash.

&Ctrl;C Edit Copy text

  Copies selected text to the clipboard.

D Edit Delete

  Moves the selected messages in the trash folder. If the selected messages are already in the trash folder, they will really be deleted.

S Edit Search messages...

  Opens up a search window that lets you search for messages with certain characteristics, &eg; a certain subject. Start the search by entering some values and press Search. Click on one of the resulting messages and it will appear in the Message pane.

&Ctrl;F Edit Find in message...

  Lets you search for a string in the current message.

K Edit Select all messages

  Selects all messages in the current folder.

&Ctrl;A Edit Select message text

  Selects the text of the currently displayed message.

#### View Menu

View Brief View Fancy Headers View Standard Headers View Long Headers View All Headers Headers

  Changes the number of headers that are displayed and the format of the headers in the Message pane.

View Iconic Attachments View Smart Attachments View Inlined Attachments

  Changes the way that attachments appear in the Message pane.

#### Folder Menu

Folder Create...

  Opens the Create Folder dialog which lets you create a new folder. You can make this new folder a sub folder if you choose a parent folder using the File under selection. If you're going to use this folder for a mailing list you may want to add the mailing list address in the Associated Mailing List tab. You can then use the Message Reply list... menu item. It will open a reply with the mailing list address in the To: field (&ie; it will ignore the Reply-To of the message). You can also click the middle mousebutton in the Folders pane to post to a mailing list that is associated with that folder.

Folder Properties...

  Opens up the Modify Folder dialog which lets you change the settings for the selected folder.

Folder Compact

  Compacts the folder file to reduce its disk space usage. Use this command if your mailboxes seem to be much larger than they ought to be.

Folder Empty

  Moves all of the messages in the selected folder into the trash folder. If the selected folder is the trash folder, the messages are permanently deleted.

Folder Remove

  Removes the selected folder.

Folder Prefer HTML to plain text

  This will show HTML messages using HTML rendering. For security reasons, we recommend to only activate this for trusted messages.

Folder Thread messages

  Shows the messages in the Header pane in a tree-like list, with replies showing up directly under the message they reply to.

#### Message Menu

&Ctrl;N Message New Message...

  Opens the Composer window so you can write a new mail. If the current folder holds a mailing list and has a Post Address defined, this address will be default To: address.

N Message Next

  Selects the next message in the Headers pane. The keyboard shortcut Right Arrow also performs this action.

+ Message Next Unread

  Selects the next unread message in the Headers pane.

P Message Previous

  Selects the previous message in the Headers pane.

- Message Previous Unread

  Selects the previous unread message in the Headers pane.

R Message Reply...

  Opens up the Composer window with the contents of the selected message's Reply-To field in the To: field.

A Message Reply All...

  Opens up the Composer window and copies the contents of the selected message's Reply-To: and To: fields into the To: field, and the Cc: field into the Cc: field of the Composer window.

L Message Reply List...

  Opens up the Composer with the To: field set to the mailing list address. Of course this will only work if you configured the current folder to be associated with a mailing list. Otherwise the To: field will be empty.

&Alt;R Message Reply without quote...

  Opens up the Composer to reply but does not quote the text of the original message.

F Message Forward...

  Forwards the message to a new recipient. The message's text will be copied into the body of the new message with a text marking the forwarded part. Attachments will be forwarded, too.

F Message Forward as attachment

  Forwards the message to a new recipient as an attachment. Attachments in the original message will also be in the forwarded message's attachment.

E Message Redirect...

  Works like forward, except that the message stays the same (even the From field). The user who redirected the message is added in special header fields (`Redirect-From`, `Redirect-Date`, `Redirect-To`, &etc;).

Message Bounce...

  Sends the message back to the sender with a notice that it cannot be delivered. This is nearly exactly the message you get from a mail relay if the user does not exist. Some people use this option to reply to spam.

Message Send again...

  Sends the message again.

Message Set Encoding

  Lets you choose the character encoding to be used in the Message Pane.

T Message Edit

  Edits the selected message if it is editable. Only messages in the outbox and drafts folder can be edited.

Message Create filter

  Opens up the Filter dialog with a new filter added. This new filter is based on the fields of the current mail.

Message Set Status

  Allows you to change the status of the selected message to one of the below (more than one status per message is currently not supported):

  - New

  - Unread

  - Read

  - Replied

  - Queued

  - Sent

Message Move to

  Moves all of the selected messages to a certain folder.

Message Copy to

  Copies all of the the selected messages to a certain folder.

&Ctrl;J Message Apply Filters

  Applies your filters to the selected messages.

Message View Source...

  Shows the message and its complete headers in plain text format in a new window. This can be useful to find out the origin of a mail. You should know that it's easy to fake the `From:` header of a mail, but one can still find out which mail servers have been used by looking at the `Received:` lines in the header.

#### Settings Menu

Settings Show Toolbar

  If enabled, the Toolbar is visible (the Toolbar is the one with the icon to compose a new message &etc;).

Settings Show Statusbar

  If enabled, the Statusbar is visible (the Statusbar is the small one on the bottom which shows useful short messages and link targets).

Settings Configure Key Bindings...

  Opens a window that lets you configure the keyboard shortcuts for many menu commands.

Settings Configure Toolbars...

  Opens a window that lets you choose which icons are visible in the toolbar.

Settings Configure KMail...

  Opens the Configure window.

Settings Configure Filters...

  Opens the Configure Filters... window.

#### Help Menu

F1 Help Contents

  Invokes the &kde; help system with the &kmail; help pages displayed.

ShiftF1 Help What's This?

  Selecting this option changes the cursor to an arrow with a question mark. If you now click on any component of the control panel pane, you get short context sensitive help about that item (sorry, this feature is not implemented yet for most parts of &kmail;).

Help Report Bug...

  Opens a window for you to report a bug. You have to be connected to the Internet to send the bug report.

Help About KMail

  Displays information about &kmail; (version, authors, license agreement).

Help About KDE

  Displays information about &kde;.

### The Composer Window

#### Message Menu

&Ctrl;Return Message Send

  Sends the message immediately.

Message Queue

  Queues the message in the outbox for sending it later.

Message Save in drafts folder

  Save the message in the drafts folder so you can edit and send it later.

Messages Insert File...

  Inserts the selected text file into the message, starting at the cursor position.

&Ctrl;P Message Print...

  Prints the current text.

Message Addressbook...

  Opens up the address book.

&Ctrl;N Message New Composer...

  Opens up a new Composer window.

&Ctrl;W Message Close

  Closes this Composer window.

#### Edit Menu

&Ctrl;Z Edit Undo

  Undo your steps in editing the current mail.

&Ctrl;ShiftZ Edit Redo

  Redo your steps in editing the current mail.

&Ctrl;X Edit Cut

  Cutting text works as with most editors. You can also select text and drag it to a new position.

CtrlC Edit Copy

  Copying text works as with most editors. You can also select text while holding the &Ctrl; key, and drag it to a new position, to have it copied and not cut.

&Ctrl;V Edit Paste

  Pasting works the same as for most editors.

&Ctrl;A Edit Select All

  Selects all of the text in your message.

&Ctrl;F Edit Find...

  Finds strings in the message.

&Ctrl;R Edit Replace...

  Lets you replace strings in your message with other strings.

Edit Clean Spaces

  This replaces multiple spaces with single spaces in the current selection or in the complete message if there is no selection.

Edit Spelling...

  Uses &kspell; to check the spelling in the body of your message. Note that you have to configure &kspell; with Settings Spellchecker... if you use it for the first time.

#### View Menu

This menu lets you toggle the display of the header fields and other options in this Composer window.

Options available are:

- All Fields

- Identity

- Mail Transport

- From

- Reply to

- To

- Cc

- Bcc

- Subject

Currently visible items have a checkmark shown next to their name in the menu.

#### Options Menu

Options Urgent

  Sets the priority of the message to Urgent. The receiver's mail client has to support this or it will have no effect. &kmail; itself does not support priorities for incoming messages.

Options Confirm delivery

  If you choose this option, you request a confirmation email once your message is successfully delivered to its destination mail server. This has to be also supported from the receiver's side in order to work.

Options Confirm read

  If you choose this option, you request a confirmation email once your message is downloaded and read by its recipient. This has to be supported and enabled by the receiver's mail client in order to work.

Options Set Encoding

  Set the charset encoding of this message. It will appear in the header of the outgoing mail.

Options Wordwrap

  Toggle the automatic wordwrap. It may be useful to turn it off if you want to paste long lines that shouldn't wrap.

#### Attach Menu

This menu lets you select attachment options.

Attach Append Signature

  Appends your signature (footer) to the end of the message.

Attach Attach Public Key...

  Attaches the corresponding PGP/GnuPG key to your message using the default encoding.

Attach Attach My Public Key

  Attaches your PGP/GnuPG public key to your message using the default encoding.

Attach Attach...

  Attaches a file to the message using the encoding you select in the dialog. The dialog allows to select more than one file using the &Ctrl; key.

Attach Remove

  Removes the attachment that is selected in the attachment window.

Attach Save...

  Saves the attachment that is selected in the attachment window to a file.

Attach Properties...

  Displays the properties of the attachment that is selected in the attachment window.

#### Settings Menu

Settings Show Toolbar

  If enabled, the Toolbar is visible (the Toolbar is the one with the icon to send the message &etc;).

Settings Show Statusbar

  If enabled, the Statusbar is visible (the Statusbar is the small one at the bottom which shows useful short messages).

Settings Configure Key Bindings...

  Opens a window that lets you configure the keyboard shortcuts for many menu command.

Settings Configure Toolbars...

  Opens a window that allows you to decide which icons appear in the toolbar.

Settings Spellchecker...

  Allows you to configure &kspell;, &kde;'s spellchecker.

#### Help Menu

The entries in this menu have the same meaning as the entries in the Mailreader's help menu.

## Frequently Asked Questions (&FAQ;)

My folders keep growing even when I delete messages.

To really remove deleted messages from disk, you have to compact your folders using File Compact all folders (by default, this will also happen every time you exit &kmail;).

However, there's a know bug that made it into the release of &kde; 2.2.0 (&kmail; 1.3): sometimes folders don't get compacted anymore, neither manually nor automatically. Here's a workaround: edit the `~/.kde/share/config/kmailrc` file, search for all occurrences of Consistent=false and replace them with Consistent=true (&kmail; must not be running while you are doing this). This bug will be fixed in KDE 2.2.1 which will probably be released in September 2001.

The <To or Cc> doesn't contain `xxx` filter criterion doesn't work.

This not strictly a bug, but a bit unintuitive. The source of the confusion seems to stem from the fact that people think <To or Cc> doesn't contain `xxx` should mean that neither To nor Cc should contain `xxx`. This interpretation assumes that using doesn't contain means negation of the whole rule. This is not the case.

In fact, doesn't contain is just another operator, just like contains. It doesn't mean negate the rule. Just like <To or Cc> contains `xxx` means To contains `xxx` or Cc contains `xxx`, <To or Cc> doesn't contain `xxx` means To doesn't contain `xxx` or Cc doesn't contain `xxx`.

You can emulate the other behaviour by using two rules: One for To and one for Cc. One of the next versions of &kmail; will include an overhaul of the search criteria, which will make it possible to easily use the above semantics.

When I reply to an email there is a special character one line before the signature. I get a warning about a changed character set when I try to send the mail.

Upgrade to Qt-2.3.1.

Where can I get a list of changes between the versions of &kmail;?

The welcome screen lists all important changes for its release. It is displayed when you start a new version of &kmail; the first time. You can always look at it again by selecting the root element of the folder list, &ie; Mail.

Can I configure the location of my mail directory?

Exit &kmail;, make a backup of `~/.kde/share/config/kmailrc`, then open it with an editor and add &eg; `folders=/home/username/.mail` to the [General] section. Then move all your existing folders (including the hidden index files) to the new location. The next time you start &kmail; it will use `/home/username/.mail` instead of `/home/username/Mail`. Note that &kmail; will lose its filters if you change the mail directory's location but forget to move your existing folders.

The button to sign messages is not enabled anymore, it was enabled some time ago.

Enter your PGP User Identity in the Identity configuration dialog. Without a PGP User Identity &kmail; can't know which key should be used to sign your messages with.

I'm one of those people whose mails consist of 100 quoted lines and one line written by myself. For some reason (which I don't get) this annoys other people. Can &kmail; help me and make everyone's life better?

Sure. Just select a short relevant part of the original mail with the mouse before you reply. Only this part will then be quoted in your reply.

&kmail; disappears/crashes while fetching mail.

Make sure you have enough free disk space. &kmail; currently does not handle the situation of a full disk gracefully and quits. Note: &kmail; does protect your data, messages that could not be saved to disk is left on the server.

Does &kmail;'s address book support distribution lists?

No. As a workaround you can add several email address into one address entry if you are using the traditional &kmail; address book.

For some messages the value in the Date field is wrong, it shows Wed Dec 31 17:00:00 1969.

Probably the Date: header of these messages is broken, maybe it's missing the time zone information. For this case we've added a workaround to mimelib. In &kde; 2.2 mimelib is part of the kdenetwork package, you must make sure that &kde;'s mimelib is used and not a different one on your system.

My signature has two dashes above it. This makes me very sad.

Separating the signature from the message body with two dashes and a space is a common and useful kind of standard. If you have strong feelings about this I suggest you modify the &kmail; source to remove that line.

&kmail; fetches the same messages over and over again.

This happens if you have Delete mail from server deselected and your POP3 server doesn't support the UIDL command. There's currently no workaround besides selecting Delete mail from server. A more detailed explanation can be found in this mailing list post.

Does &kmail; support IMAP?

Yes, it does so since &kde; version 2.2. It's not yet feature complete, but it should be enough for many users. We know of those limitations, so please don't submit wishlist reports about them.

Are there any known bugs in &kmail;?

You can find a list of submitted bugs at bugs.kde.org. Note that not all these bugs are valid, all in all we think that &kmail; is now a very good piece of software.

However, you should not run &kmail; while another mail client is already accessing the files in `~/Mail`. If you try to do so, you might lose messages. Note that you should make backups of your messages anyway.

&kmail; doesn't display HTML mail as HTML, I can only see the source.

Select Folder Prefer HTML to plain text. For security reasons you should only do so for trusted mails. Note that plugins (like Macromedia Flash), Java and Javascript will not be displayed in &kmail; and there's no way to activate them.

Can I use two different version of &kmail; at the same time? Can I go back from a current version of &kmail; to an older one?

You can only run one instance of &kmail; at once. We recommend also to stick to a certain version and not switch back and forth between different versions. Downgrading to an older version might cause problems, &eg; because the index file formats might have changed. Upgrading should never be a problem.

Does &kmail; support uuencoded files?

No. However, you can handle them using a filter, which is described in this posting to the mailing list.

&kmail; crashed while I was writing a mail. So this mail is lost now?

&kmail; tries to save your mail to `~/dead.letter` in case of a crash. The next time you start &kmail; the mail composer should appear with your mail again. If it doesn't, try to open `~/dead.letter` with an editor. If it doesn't exist, the crash was so bad that &kmail; couldn't save your mail.

When I try to set a folder to be mailing list-aware, it does not do anything when receiving an email from the list.

Associating a folder with a mailing list has nothing to do with filtering the mailing list messages. You have to add a new filter rule manually. However, once you associated a folder with a mailing list you can use Message Reply List... or Message New message... and the mailing list address will be set to the To: field.

My SMTP server requires authentication. Does &kmail; support it?

There are two common techniques used for SMTP authentication: SMTP after POP3 and SMTP Auth. SMTP Auth is currently not supported. To use SMTP after POP3 you have to collect all your mails in the outbox and send them just after you have fetched new mail.

Can I use &kmail; and procmail?

Yes, but it's important to do it the right way or you might lose mail. In order to use procmail and &kmail; you need to set up KMail so that it will fetch new mail from the spoolfiles in which procmail drops your mail. Do not set up procmail to deliver mail in a KMail folder, this cannot work.

For each procmail spoolfile, you then need to create an account from which &kmail; will fetch new mail. You also need to make sure you specify the right lockfile name for this account. When setting up an account, &kmail; will do some minimal parsing on your procmail file, and will try to list every spoolfile it has found, and also the lockfiles next to the "procmail lockfile" item. procmail lets the user specify lockfiles in three different ways, so there's no way to establish a correspondence between the spoolfiles and lockfiles. So it's really up to you to make sure you specify the right lockfile for each spoolfile.

What should I know if I want to use PGP/GnuPG with &kmail;?

&kmail; provides a simple and easy to use interface for basic functions of these programs. Still you should understand how these programs work and what might make their use insecure. Some important issues:

- You really should test if encryption works before you use it. &kmail; relies on PGP/GnuPG's error strings, which often change between different versions.

- Trusting a foreign public key without checking it is no good idea.

- &kmail; will not encrypt messages with an untrusted (unsigned) public key if you use PGP. If you use GnuPG &kmail; will encrypt messages with untrusted public keys.

- As most other mail clients, &kmail; can encrypt your messages, but not your attachments. You have to encrypt them manually before you attach them.

How do I have to set up &kmail; to use (&ie; read and write) messages with non-Latin1 characters?

In the Appearance/Fonts section of the Configure &kmail;... dialog, select the correct Character set for the message list and the folder list. If unicode (iso10646-1) is available, you should choose it. In case messages are still not shown correctly, you can always try other settings from the Message Set Encoding menu. For writing messages, go to Composer/Charset and configure the default charset you want to use for your own mails.

Spellchecking doesn't recognize non-english characters.

Before you can use spellchecking the first time, you have to configure it. You can do so in the Composer window's menu under Settings Spellchecker.... You can set the dictionary and the encoding there.

How do I use my Eudora/&Netscape;/Outlook/... mail folders in &kmail;?

See the section Using other Mailbox files With &kmail;.

How can I use mail folders that are not in `~/Mail/`?

Simply create a symlink in your `~/Mail` directory using ``ln` `-s` `/somewhere/Mail/mymailboxfile` `~/Mail/remote``. When you start &kmail; you will see a new folder with the name remote that contains the mails in your remote folder. If you want to add a whole remote mail directory use ``ln` `-s` `/somewhere/Mail` `~/Mail/.remotedir.directory``. For that case you also need to create a new empty folder named `remotedir` with &kmail;. The folder `remotedir` will then contain all remote mailbox folders as subfolders.

Can I use encryption with my normal (non-SSL) POP3 account?

If your POP3 server runs an ssh daemon, you can use ssh to tunnel your POP3 connection using the following command:

``ssh` `-L 110:127.0.0.1:110 user@host``

Modify your &kmail; configuration to fetch the mail via POP3 from `localhost` and ssh will tunnel the connection for you. You need to be root to execute this command. Alternatively, change the first port number, &ie; the first occurrence of `110`, to something above 1024 and configure &kmail; to use that port.

If non-encrypted mails have already been sent via internet, the only advantage of using ssh is that your password will be sent encrypted to the POP3 server.

Does &kmail; lock the folders it uses?

&kmail; does not lock the files in `~/Mail`.

To avoid the risk of losing mail if using a local account it is necessary to ensure that &kmail; uses the same type of locking as your mail delivery agent.

There are five different locking options you can use:

- Mutt dotlock (recommended)

- Mutt dotlock privileged

- Procmail lockfile

- FCNTL (default)

- none (use with care)

Mutt dotlock and Mutt dotlock privileged will both use a small utility that comes with mutt called `mutt_dotlock`. Mutt dotlock can be used in the same way as the Procmail lockfile option, with the same limitation with regards to the `/var/spool/mail/` folders. However, the Mutt dotlock privileged option can create lock files in the `/var/spool/mail` directory. `mutt_dotlock` is a setgid program and this option will run it in setgid mode. Please note that these options will only work if mutt is installed on your system.

Procmail lockfile will use a small utility that comes with procmail called `lockfile`. You can use this if your mail folder is in a directory where you have write permissions. This will not work on your `/var/spool/mail/user` file in most cases. It will create `.lock` files on your account when &kmail; is checking for new mail. Please note that this will only work if procmail is installed on your system.

FCNTL: the default option will use the `fcntl()` system call.

If you don't want to use any locking, the none option is what you want. However, there are risks of losing mail when no locking is used.

How do I leave mail on the server?

Open up the Settings Configure &kmail;... window. Click on the Network tab. Select your account from the account list and click the Modify... button. This dialog contains the Delete mail from server setting which you must not select.

How do I automatically insert a text footer within my mails?

The text footer is called a signature file. Select Settings Configure &kmail;... Look in the Identity tab for the Specify signature below field. Select the radio button and type your signature below.

Why does &kmail; keep asking me for the location of my signature file?

&kmail; will ask you for the location of your signature file if you have checked the option Automatically append signature in the Composer tab of the Configure &kmail;... dialog, but you have not specified a signature file in the Identity tab. You should either specify a signature file, select Use signature below, or deselect Automatically append signature.

How do I set up sendmail to work with &kmail; if I have a dial-up connection?

First you should check if your &Linux;/BSD/whatever distribution can do this for you. It probably has already been set up during installation.

If that's not the case, you may want to have a look at the Mail Queue HOWTO or at UCT Linux User's group page on configuring sendmail for Dial-up connections.

I've seen demonstrations of remote control behavior with &kmail;. Is there any documentation on the available interfaces?

You can get a list of functions by using this command in a shell: ``dcop` `kmail KMailIface``. Some documentation is also in `kdenetwork/kmail/kmailIface.h` and `kdenetwork/kmail/mailcomposerIface.h`.

## Using other Mailbox Files with &kmail;

&kmail; offers an import tool for some formats. You can access it using File Import.... You only need to read this chapter if this tool does not work for you.

This section is for all of the users who need to move email messages from their previous email client over to &kmail;. &kmail; stores its mail using the `mbox` format, one of the most widely used mailbox formats on &UNIX; systems. Mbox mailboxes store messages in one file, identifying where messages start and end with a `From` line (do not mix this up with the `From:` header that contains the message's sender). For many &UNIX; mail programs, all you must do is move your mailboxes to `~/Mail` (or make `Mail` a symbolic link to the folder containing your mailboxes), make sure they are writeable by your user, and launch &kmail;. The mailboxes should now show up correctly in &kmail;.

If your old mailboxes are not in mbox format, see below for instructions on importing some other common formats. Take a look at the Download section of &kmail;'s homepage if your mailbox format is not listed here.

Do not use a second mail client that accesses the files in `~/Mail` while &kmail; is running or you might lose messages. This section only explains how to import mailboxes to &kmail; once, it's not useful to you if you're planning to use several mail clients for your mailboxes in the future.

Eudora Lite/Eudora Pro

  Eudora uses the mbox format in its mail files. To use them with &kmail;, make sure that your Eudora mailboxes have been compacted, then copy the `.mbx` files (&Windows; Eudora) or Eudora mailbox files (&Mac; Eudora) to your `~/Mail` directory. You don't need to copy the `index` files. Once you start &kmail;, the mailboxes should appear in the Folders pane and the messages should be accessible in the Headers pane.

  If messages do not appear in the Headers pane, your mailbox files may still contain &Windows; or &Mac; line feed characters. Use your favorite text editor, the recode command or a scripting language to change the &Windows; or &Mac; line feeds to &UNIX; line feeds.

MMDF

  This format is close enough to the mailbox format that &kmail; should be able to use these mailboxes if you just copy them to your `~/Mail` directory. However, MMDF mailboxes have not been tested with &kmail;, so your results may vary. If you can get this format to work with &kmail;, please let us know so we can include more specific directions in the next documentation release.

MH mailboxes

  MH mailboxes are directories containing files that correspond to each message in that mailbox. A shell script to convert MH mailboxes to mbox mailboxes, `mh2kmail`, is included at least in the source releases of &kmail;, but maybe not in the packaged releases. Running this script on a MH folder will convert it to an mbox file. We strongly suggest that you back up your MH mail folders before you use this script.

Forte Agent

  In Agent:

  1. Select the messages to export

  2. Select FILE SAVE MESSAGES AS

  3. Mark the UNIX FORMAT and SAVE RAW boxes

  4. Give File a `.txt` extension and save.

  In &kde;:

  1. Move previously saves file to correct `~/Mail` folder

  2. Rename file without `.txt` extension

  When you open &kmail; the new folder with appropriate messages will be there.

&Netscape; Mail

  Copy your &Netscape; mail files from `~/nsmail/` to `~/Mail` and make sure they are writeable (only by your user, of course). The mailboxes will show up in &kmail; the next time you start it.

Pegasus Mail

  Pegasus for win32 uses single files for Mail folders similar to &kmail;. Pegasus mail folder files have the extension `.pmm` but they are the same format as mbox except the messages do not start with the `From` header, but with a control character. To work around this, replace each instance of the control character with `From aaa@aaa Mon Jan 01 00:00:00 1997`. This `From` line should be the first line of every message, before the `Received:` and other headers. Make sure to use a text editor that lets you save the files in &UNIX; format or create new folders in Pegasus that are in &UNIX; format and copy your mails there.

Maildir / Outlook Express / xfmail

  Tools to convert these formats are available at the Download section of &kmail;'s homepage.

Lotus Notes, BeOS Mail files, cc: Mail, &etc;...

  First you should have a look at Download section of &kmail;'s homepage if there are tools to convert mails.

  Mail programs not listed here or on the homepage probably do not work with &kmail; as they use proprietary mail formats that &kmail; cannot understand. However, there is no harm in trying! If the mailbox file looks similar to the mbox format, try copying the mailbox file (remember, the index file is not needed) to your `~/Mail` directory and see what happens if you start &kmail;. If you get mailboxes from your favorite mail client to work in &kmail;, please tell us how you did it so that we can include directions in a future revision of this documentation.

## Credits and Licenses

&kmail;: Copyright the &kmail; developers, 1997-2001

&underGPL; &underFDL;

### Original Developers

- Stefan Taferner taferner@alpin.or.at

- Markus Wuebben markus.wuebben@kde.org

### Current Team

- Waldo Bastian bastian@kde.org

- Andreas Gungl a.gungl@gmx.de

- Michael Haeckel michael@haeckel.net

- Lars Knoll knoll@mpi-hd.mpg.de

- J. Nick Koston bdraco@darkorb.net

- Marc Mutz mutz@kde.org

- Daniel Naber daniel.naber@t-online.de

- Sven Radej radej@kde.org

- Espen Sand espen@kde.org

- Don Sanders sanders@kde.org (Active maintainer)

- George Staikos staikos@0wned.org

- Mario Weilguni mweilguni@sime.com

- Robert D. Williams rwilliams@kde.org

### Documentation

Update for &kmail; 1.2 and 1.3 by Daniel Naber daniel.naber@t-online.de, PGP part by Andreas Gungl a.gungl@gmx.de, filter part by Marc Mutz Marc.Mutz@uni-bielefeld.de. Other parts have been contributed by the various &kmail; developers.

&kmail; 1.0 documentation by David Rugge davidrugge@mindspring.com. Original documentation by Markus Wuebben markus.wuebben@kde.org, Robert Williams rwilliams@kde.org (Editor).

Thanks to Michael Elkins me@cs.hmc.edu for his excellent description of the different Unix mail formats in the Mutt documentation.

Thanks to the following people for providing directions on using other mail client mailboxes with &kmail;:

- Mendel Mobach mendel@mobach.nl (&Netscape; mail)

- Ed Shapard shapard@bigfoot.com (Pegasus Mail)

- Ray Muir rjmuir@ibm.net (Forte Agent)

## Installation

### How to obtain &kmail;

&kmail; is part of the &kde; project http://www.kde.org. &kmail; can be found in the kdenetwork package on ftp://ftp.kde.org/pub/kde/, the main &FTP; site of the &kde; project.

### Compilation and Installation

In order to compile and install &kmail; on your system, type the following in the base directory of the kdenetwork distribution:

    % ./configure
    % make
    % make install

Since &kmail; uses autoconf and automake you should have no trouble compiling it. Should you run into problems please report them to the &kde; mailing lists.