# The &kmail; Handbook

Daniel
Naber
David
Rugge
11/03/2001
1.02.00
1999
2000
2001
David Rugge

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

KDE
Mail
email
Client
POP3
PGP
GnuPG

## 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 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 space to select the folder you navigated to.

- When you are writing a new mail and you are in the To: field, only type the first few characters of the receiver's address, then press &Ctrl;T to get a list of choices. These are taken from your address book, so keep your address book up to date and this feature will be very useful.

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

&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 Configuration... 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 email 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.

Finally, set the location of your signature file in the Signature File field. You can skip setting the signature file if you do not have one, but every time you compose a new message, &kmail; will ask you for your signature file. So if you don't want one, select Specify signature below and just don't enter anything in the field below. If you want a random signature, you may specify a program and check the The file is a program box.

### 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 pick or what to put in a field, consult your Internet Service Provider (ISP) or System Administrator.

#### Properties

The Properties section lets you customize 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.

#### Sending Mail

The Sending Mail section provides two options for sending mail: 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.

#### 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 (IMAP accounts are not yet supported). 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. Again, you should not need to change the Port setting (the default is 110).

If you select Store POP 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 the password, so people who can access your configuration files (&eg; system administrators) can get your password if you select this option.

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

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 mail on this account with File Check Mail in.

Select Enable interval mail checking if you want &kmail; to check for new mail 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 &kmail; will execute just before fetching mail. Please specify the full path and note that &kmail; will not continue until the program returns.

You are now ready to send and receive mail!

### Testing your Setup

First, you should send an email to test your configuration. To send an email, hit &Ctrl;N, select the Compose 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 mail by selecting Message Send.

To check your email, select File Check Mail. In the lower right corner of the main window, a progress bar will indicate how much mail is 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 Configuration...

## Using &kmail;

### The Mail Reader Window

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

Folders pane (upper 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/Addressbook in the Configure 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) 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.

Message pane (lower 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
  --- | ---
  right arrow or N | Next message
  left arrow key or P | Previous message
  + | Next unread message
  - | Previous unread message
  Ctrl+ | Go to next folder with unread messages
  Ctrl- | Go to the previous folder with unread messages

Messages can have one 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 mesage has been queued in the outbox to be sent later.
Sent | Angled envelope | The message has been sent.

### 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 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. If you already started typing an address you can also press &Ctrl;T to get a list of possible completions. 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:

- Push 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.

- Selecting 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 file 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 should then 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.

#### 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 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; 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 Modify... .

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 is a place to 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 dialog.

The address book described in the following is the Traditional KMail address book. The other address books should come with their own documentation, as they are in fact independent programs.

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. 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.

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

If you ever need to remove a filter, select it from the Filter Rules window and press the Delete button.

#### Filter Action

The most common use of filters is to sort incoming messages to certain folders. This can be done by choosing transfer. But there are other actions a filter can start:

transfer

  This will move the message to another folder.

set identity

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

set transport

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

set Reply-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.

execute

  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.

filter app

  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 &kde; User List, I could create a folder for the list (I'll call it KDE-User) and use a filter to automatically transfer new messages from my inbox to my KDE-User folder if they are from the &kde; User List. Here is how to create this filter:

1. Think of a unique way of identifying the messages you want to filter. The unique property of my &kde; User List messages is that they always contain kde-user@kde.org in the To: or Cc: field.

2. Select Settings Filter Rules....

3. Press the New button to create an empty filter. It will appear as Unnamed.

4. The right side of the Filter window contains two sections: matching criteria and actions. In the matching criteria area, select <To: or Cc:> from the first pull-down menu, contains from the second pull-down menu, and type `kde-user@kde.org` in the text field.

5. Skip down to the actions section. Select transfer 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-User from the pull-down menu.

You may find that you need to use more complicated criteria to properly filter your messages. For example, you may only want to filter the &kde; User 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:

1. Open up the Filter Rules window and select the filter you just created.

2. Since you want to filter all messages that have kde-user@kde.org in the To: or Cc: field and that are from Fred, select the and option from the pull down menu between the two criteria sections.

3. Now, go to the bottom criteria section 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; User List messages that are from fj@anywhere.com.

### Multiple Accounts

Multiple accounts are used to check mail from more than one email address and/or mail server. Select Settings Configuration... 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 mail from a particular account, use the File Check Mail in... submenu to select the account to use to check your 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. Working with GnuPG is generally similar, but some 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.

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;

Open the &kmail; Configure dialog and go to the Security settings page. Type your identity into the PGP user identity entry field. There are also three options:

Keep passphrase in memory

  When this option is off, then &kmail; will ask for your passphrase each time you sign a message (before sending) or decrypting a message (sent to you). 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.

  Note that a user with enough privileges (&eg; root) might be able to catch your passphrase even from the computer's memory.

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 GnuPG or PGP. 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 for each mail manually.)

Now you are able to sign outgoing messages. To let people send encrypted messages to you and to let them verify your signature you must send them your public key. 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 get a public key as an attachment or simply by ftp or 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 the key is not certified with a trusted signature, you can't use it with &kmail; to encrypt messages unless you have signed that key (use ``pgp` `-ks` identity of the key`).

#### 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.

If &kmail; can't find a key for any of the recipients, it will display a list containing all available keys. You can choose the appropriate key out of 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.

## Customizing &kmail;

&kmail;'s settings window gives you a number of ways to customize &kmail; to your needs.

### Identity Tab

Please see Getting Started section.

### Network Tab

Please see Setting up your Account section.

### Appearance Tab

#### Fonts

This section allows you to change the type, size and character set of the display fonts.

#### 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

This section lets you toggle the long folder list on and off. The long folder list lists folders all the way down the left side of the &kmail; window, which lets you see more folders than in the default 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 next to that message.

Prefer plain text to HTML rendering will try to show even HTML mails as plain text. It's a good idea to prefer plain text, as security problems with HTML might show up some day.

#### Profiles

This section offers several default settings for colors and font sizes.

#### Addressbook

This section allows you to choose between several address books, whereas Traditional KMail is a very simple one and Abbrowser is an advanced one. Please note the comments under the selection that tell you the packages you need to use the advanced variants. The address books' database is independent, &ie; you will not see addresses in the Abbrowser if you only entered them in the Traditional KMail address book.

### Composer Tab

#### General

The Phrases section lets you define the automatically generated lines 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, and %_ to insert a space. 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.

Use smart quoting will break long lines but will try to keep the correct quoting (e.g. 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 mail 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.

#### 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 (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 Mime Headers section lets you define fields that &kmail; will use for its outgoing message headers. You can both invent new fields and overwrite existing ones. This feature is probably only useful for advanced users.

### Security Tab

See the PGP section.

### Miscellaneous Tab

Empty trash on exit

  The trash folder is cleared of messages when you quit &kmail; if this option is selected.

Send Mail in outbox Folder on Check

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

Automatically send receive and read confirmations

  With this option, a confirmation is automatically send to the sender of a message if he requested that. If you disable this option, no confirmation will be sent.

Compact all folders on exit

  This will compact all folders every time you exit &kmail;. Compacting folders means that the messages you removed from a folder 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 emtpy the folder.

Use external editor instead of composer

  If you don't like the Composer you can use any 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.

New Mail Notification

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

## Using other Mailbox Files with &kmail;

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 it up with the `From:` header that contains the message's sender). For many &UNIX; mailers, 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.

## Menus and Keyboard Shortcuts

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

### The Main Mail Reader window

#### File Menu

File New Mail Client...

  Creates a new Mail Reader 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 mail in all your accounts, except those that have Exclude from "Check Mail" enabled.

File Check Mail in...

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

File Send Queued

  Sends the messages that are in your outbox.

File Address Book...

  Opens up the Address Book.

&Ctrl;W File Close

  Closes the current Mail Reader 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.

#### 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 formatting 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 Modify...

  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.

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.

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.

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 Set Status

  Allows you to change the status of the selected message to one of the below:

  - 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 the receiver 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 Configuration...

  Opens the Configure window.

Settings Filter Rules...

  Opens the Filter Rules 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, not implemented yet).

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.

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 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;)

Does &kmail; support IMAP?

Not yet. However, IMAP support is now in active development and will probably be part of the &kmail; version that comes with &kde; 2.2. Until then, you can receive mails via IMAP by using fetchmail:

1. Create a file `~/.fetchmailrc` which contains the following lines:

       poll <your-mail-server>
       proto IMAP
       user your-username
       pass your-password

   If your mail username and your local username differ you have to add the following entry:

       is local-username

2. Execute ``chmod` `700` `~/.fetchmailrc``

3. Create a local account in &kmail;

4. Enter `fetchmail` in the field Precommand. This is not necessary if you have a permanent connection to the net. In that case you are better off leaving fetchmail running as a daemon. This also has the advantage that you won't have to add your password to `~/.fetchmailrc`, you will be asked for it when the daemon starts.

5. Check your mail

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.

&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) will not be displayed in &kmail;.

Does &kmail; support APOP?

Yes, APOP is used automatically if it's available. There's currently no feedback if it's used, and no way to check.

Can I use &kmail; and procmail?

Yes, but it's important to do it the right way or you might lose mail. Do not let procmail sort the mail to `~/Mail`, but to some other directory which you then access by &kmail; as a Local Mailbox. That is, you have to add another account in the Network tab of the Configure dialog. Also see the &FAQ; about lockfiles.

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 them insecure. 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.

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

- There's a bug in &kmail; 1.1.99 (which comes with &kde; 2.0 and 2.0.1) that makes PGP not work if you use a different language than English. You can work around it this way (&kmail; will still use your favourite language):

  1. Rename `/usr/bin/kmail` to `/usr/bin/kmail.original`

  2. Install in `/usr/bin` the following shell script, calling it `kmail` and making sure it is owned by root and has `755` permissions (`rwxr-xr-x`):

         #!/bin/bash
         LANGUAGE=en
         export LANGUAGE
         kmail.original $*

- &kmail; is not able to use different keys for multiple identities.

Which version of &kmail; supports which version of PGP/GnuPG?

Since &kmail; 1.2 you can choose which encryption tool to use if you have more than one. All the programs that are listed in the Security tab of the Configure dialog are supported.

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 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....

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.

My folders keep growing even when I delete messages.

To really remove deleted messages from disk, you have to compact your folders. To do so automatically, open up the Settings Configuration... window, select the Miscellaneous tab and select Compact all folders on exit. Maybe you want to select Empty trash on exit, too. This will remove all the messages in the trash folder whenever you exit &kmail;.

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 occurence 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 Configuration... 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 Configuration... 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 the location of your signature file if you have checked the option Use a signature from file in the Composer tab of the Configure dialog, but have not specified a signature file in the Identity tab. You should either specify a signature file or deselect Use a signature from file.

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. Perhaps it 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.

## Credits and Licenses

&kmail;

Copyright the &kmail; developers, 1997-2001

&underFDL; &underGPL;

### 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

- 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 by Daniel Naber daniel.naber@t-online.de, PGP part by Andreas Gungl a.gungl@gmx.de

&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.