# &Balsa; User's Guide

Pawel Salek
1997-2009 Stuart Parmenter and others, see AUTHORS for a list of people

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.

UNIX is a trademark of X/Open Group.

Linux is a trademark of Linus Torvalds.

X Window System is a trademark of X Consortium, Inc.

Windows is a trademark of Microsoft Corp.

Macintosh and Apple are trademarks of Apple Computer, Inc.

All other trademarks are property of their respective owners.

This is version 2.721 of the Balsa manual.
2.721
26 February 2006

This document is the extensive balsa manual.

&Balsa; is a graphical mail client. While it is in active development, &Balsa; has many features such as: &IMAP; and &POP3; support; sendmail or direct &SMTP; support; optional multi-threaded retrieval and sending of messages; support for all configurations of local mail folders; automatic mail checking; mail printing; inline attachment viewing; and the proverbial much, much more.

This document will introduce a person who understands mail to using &Balsa;. However, it will not explain email to a confused individual. If you're looking for that, try asking a friend or visiting the Email FAQ.

## Introduction

&Balsa; is a graphical mail client. It supports the standard features of any good reader and has new features added continually. See the abstract above for a quick feature rundown.

&Balsa; is written using GTK+ and GNOME. Originally based on libmutt, the back end code to &Mutt;, &Balsa; now uses a combination of GMime for handling Mime messages, and its own drivers for local and remote mailstores.

If you want to learn more about &Balsa;, your best bet is the &Balsa; Discussion forum on the website &balsalist;. Bugs can be reported via GNOME GitLab.

## Getting Started with &Balsa;

If you're starting &Balsa; for the first time, the first thing you'll see is an assistant that will set up &Balsa;'s basic settings. &Balsa; can guess most of what it needs to know about you. It will also create five standard local mailboxes: the Inbox, Outbox, Sentbox, Draftbox, and Trash. (These can be changed to be &IMAP; mailboxes later.)

&Balsa; Start Assistant

Don't worry. &Balsa; cooperates with other MUA's very well. They share the same locking semantics for mailboxes. If &Balsa; shares the same mail directory as &Pine; or &Mutt;, it will detect new folders as they are created. So if you have to telnet in to your mail machine, you won't be stuck.

There are many more settings in &Balsa;'s preferences window, but most of them do not need to be changed.

Once &Balsa; is configured, you will proceed on to the main window.

## The Main Window

Main Window

&Balsa;'s main window has three major areas. To the left is the mailbox list. This displays all the mailboxes &Balsa; knows about; it will scan for ones in your local mail directory. (This means &Balsa; works well with &procmail;.) It will also list &IMAP; mailboxes that you have configured. If the Show Mailbox Info preference is set, two columns will also be displayed next to the mailbox names containing the number of unread and total messages in each mailbox that has unread messages; otherwise, the number of unread messages is shown in parentheses after the mailbox name. Also, any mailboxes that contain unread messages will be shown in a bold font.

At the top-right is a view of the currently open mailbox, called the message index. You can browse messages and manipulate them here.

At the bottom-right of &Balsa;'s main window is the message view. This displays the message selected in the message index. You can save attachments, view attachments, and read incoming email here.

### Menu & Toolbar

Main Window Toolbar

The menu bar, located at the top of the Main Window, provides the following commands:

File

  This menu contains basic commands.

  - File New

      - M File New Message... — Create a new message, and display a new window to type the message in.

      - File New Mailbox... — Open a dialog box to create a new mailbox. There are various items like this, corresponding to the different types of mailbox that &Balsa; supports. See the discussion of different mailbox formats and their advantages and disadvantages.

      - File New Remote IMAP folder... — Open a dialog box to create a folder for an account on an IMAP server. This IMAP folder properties dialog can also be used to change the details of the account.

      - File New Remote IMAP subfolder... — Open a dialog box to create a new subfolder in an existing IMAP folder tree. This IMAP subfolder properties dialog can also be used to rename or move a subfolder.

  - C File Continue — Continue a postponed message.

  - Ctrl M File Get New Mail — This causes &Balsa; to attempt to retrieve any new messages from the &POP3; server.

  - Ctrl T File Send Queued Mail — Send all mail waiting in the Outbox mailbox to the mail server now.

  - Ctrl B File Send and Receive Mail — Send all mail waiting in the Outbox mailbox to the mail server now and retrieve any new messages.

  - File Page Setup — Set print options such as paper size and print orientation.

  - File Print — Print the currently selected message (displayed in the message view pane.)

  - B File Address Book — Open &Balsa;'s address book.

  - File Exit — Exit the program.

Edit

  - Edit Copy — Copy selected text to the clipboard.

  - Edit Select All — Select all text in the currently displayed message.

  - Edit Select Thread — Select all messages in the same thread as the currently displayed message.

  - Edit Find — Find messages in the current mailbox that match a given set of conditions, using the search mailbox window.

  - Edit Find Next — Find the next matching message.

  - Edit Find in Message — Selecting this option opens a search bar at the foot of the message preview, in which you can type text for which &Balsa; will search in the current message.

  - Edit Filters — Open up the filters window.

  - Edit Export filters — Open up a window for exporting filters in the Sieve format.

  - Edit Preferences... — Open the Preferences window to change the settings of &Balsa;.

View

  Menu for changing how messages are viewed.

  - View Show Mailbox Tree — Toggle the display of the mailbox tree in the main window.

  - View Show Mailbox Tabs — Toggle the display of tabs for all open mailboxes.

  - View Wrap — Toggle the display of messages using word wrap. The column to which the message is wrapped is set in the Preferences window.

  - View No Headers , Selected Headers , All Headers — Select the headers to display in the message pane.

  - View Flat index , Simple threading, JWZ threading — Select the type of threading used to display the messages in the message index.

  - Ctrl E View Expand All — Ctrl L View Collapse All — Expand or collapse all threads in the currently displayed mailbox.

  - View Zoom In , Zoom Out, Zoom 100% — Alter the font size of HTML messages. Plain text messages will always use the font specified in the Preferences window.

Mailbox

  For manipulating mailboxes.

  - N Mailbox Next — Select the next message in the current mailbox.

  - P Mailbox Previous — Select the previous message in the current mailbox.

  - Ctrl N Mailbox Next Unread — Select the next unread message in the current mailbox.

  - Ctrl Alt F Mailbox Next Flagged — Select the next flagged message in the current mailbox.

  - Mailbox Hide messages — A submenu listing all the types of messages that may be hidden and unhidden in the current mailbox. Types in the submenu are toggled when selected. A Checkmark indicates it is currently hidden.

  - Mailbox Reset Filter — Resets to the mailbox filter.

  - Mailbox Select All — Selects all messages in the current mailbox.

  - Mailbox Edit... — Edit mailbox properties.

  - Mailbox Delete... — Delete the currently selected mailbox.

  - Mailbox Expunge Deleted Messages — Physically remove from the backing mailstore all messages marked as deleted.

  - Mailbox Close — Close the currently selected mailbox.

  - Mailbox Empty Trash — Delete all messages from the Trash mailbox.

  - Mailbox Select Filters — Pop up a dialog that allows you to control which filters are applied to this mailbox, and optionally to apply them.

  - Mailbox Remove Duplicates — Remove duplicate messages; &Balsa; locates all messages in the current mailbox that have the same Message-ID header, and removes all but one.

### Message Menu

Message

  This menu has commands for manipulating messages.

  - R Message Reply... — Reply to the currently selected message(s).

  - A Message Reply to All... — Reply to the currently selected message(s), sending the reply to all senders and recipients of the message.

  - G Message Reply to Group... — Reply to a mailing list, instead of the sender to that list.

  - F Message Forward attached... — Forward the currently selected message(s) as an attachment.

  - Message Forward inline... — Forward the currently selected message(s), quoted inline.

  - Ctrl. Message Next Part — View the next part of the message (if the message is multi-part).

  - Ctrl, Message Previous Part — View the previous part of the message.

  - Ctrl S Message Save Current Part... — Save the currently selected part of the message to a file.

  - Ctrl U Message View Source... — Opens a new window that displays the raw message as received from the MTA.

  - Message Copy — Copies to the clipboard any text selected in the message view of the current message.

  - Message Select Text — Selects the entire text of the current message in the message view.

  - D Message Move to Trash — Moves the currently selected message(s) to the Trash.

  - Message Toggle flag

    - X Message Toggle flag Flagged — Toggle the flag on the currently selected message(s). This is shown as an exclamation mark next in the message index.

    - Ctrl D Message Toggle flag Deleted — Marks the message as set for deletion. The message will be actually removed from the backing mailstore when it is expunged either manually, or as specified in the Preferences. The icon is a small trash can.

    - Ctrl R Message Toggle flag New — Marks a message that has been read as new, and vice-versa. The message will display the standard icon and font for a new message.

    - Message Toggle flag Answered — Toggles the reply icon for a message.

  - S Message Store Address... — Add the sender of the currently selected message to your address book.

Settings

  Menu for changing &Balsa;'s configuration.

  - Settings Toolbars... — Open the Toolbars window to modify the content and arrangement of the toolbars in &Balsa;.

  - Settings Identities... — Open the Identities window to customize how you present yourself to the rest of the world.

### The Mailbox List

The mailbox list in the main window lists all of your mailboxes. &Balsa; will automatically detect your local mailboxes by searching for mailboxes under your local mail directory (probably ~/mail). This lets &Balsa; coexist with &Pine; and &procmail; without causing problems.

Your mailboxes will be displayed as a tree view, with mailboxes in subdirectories of your local mail directory initially hidden but accessible by expanding the tree. &IMAP; mailboxes will also be displayed as being at the top level of the tree. &POP3; mailboxes are not displayed.

### The Message Index

The message index displays the messages in the current folder, and lets you choose which messages to view. Click on the notebook tabs, if shown, or click on a folder in the mailbox list to bring it to the front.

From the message index you can do a lot. Clicking on a message will cause it to be displayed in the message view. Right-clicking on it will give a pop-up menu letting you reply to the message (or forward it, etc.) and move it to another folder (using the Move to menu item). Double-clicking on a message, or pressing either the space-bar or the Enter key while the keyboard focus is in the index, will open the message in a separate window. Also, it is possible to drag and drop messages from the index to other mailboxes in the mailbox list and open mailbox tabs.

The pop-up (context) menu contains the following items:

- Reply, Reply To All, Reply To Group, Forward Attached, Forward Inline, Store Address, Delete, Undelete, Move To Trash, Toggle Flagged, Toggle Unread, Move to, View Source — These perform the same actions as their counterparts in the message menu.

- Move to — Moves the currently selected message(s) to another mailbox. When this menu item is selected, a list of available mailboxes is displayed, from which the destination may be selected.

### The Message View

This displays the email that is selected in the message index. Message headers are displayed above the main text of the message, unless they have been disabled. The text of the message is shown below the headers.

If the message is multipart, an attachment icon will appear beside the headers. Clicking this icon will display a list of the parts from which you may select one. If &Balsa; is unable to display it, you will be given a choice of applications known to handle the part. Additionally, there is always an option to save the attachment to a file.

&Balsa; supports viewing HTML messages only when compiled with gtkhtml or WebKit support. Gtkhtml support will be compiled in if gtkhtml-devel files are found. WebKit is currently supported only on an experimental basis,

You are not restricted to that pane either. Double-clicking on a message in the message index, or touching either the space bar or the Enter key, will open it in a separate window.

## The Message Composer

Message Composition Window

When the New Message or Reply or Forward action is selected, the message to be sent is brought up in the Message Composer. This window is where you can type the text of the message, attach files, and specify recipients. The window also provides an interface to spell check the message. Signing and encryption of messages using GnuPG or PGP are also supported, when &Balsa; is built with cryptographic support.

When the message window first opens, you will see the several main sections:

- The menu bar

- Toolbar

- Mail headers

- The attachment box

- The message body

These will each be covered in depth below:

### Menu Bar

This contains all of the available commands for acting on the message, from selecting the headers to display to changing the character set of the message. Some of the menu items are not always available, depending on what state the message is currently in.

File

  The file menu contains commands for manipulating the message as a whole.

  - File Include File... — Include a text file in the body of the message; only works for plain text files.

  - File Attach File... — Attach any kind of file to the message.

  - File Send — Send the message.

  - File Queue — Queue the message in the outbox for sending later.

    A message is considered valid (ready for sending or queuing) if it contains at least one valid email address, and no invalid addresses, in the Recipients fields.

  - File Postpone — Save the message in the Draftbox for later revision and sending. You will be unable to postpone a message that is not currently valid.

  - File Page Setup — Set print options such as paper size and print orientation.

  - File Print... — Print a hard-copy of the current message.

  - Ctrl W File Close — Close and discard the current message.

Edit

  The Edit menu contains commands which are used to modify the body of the message.

  - Ctrl X Edit Cut — Cut the selected text to the clipboard.

  - Ctrl C Edit Copy — Copy the selected text to the clipboard.

  - Ctrl V Edit Paste — Paste the contents of the clipboard to the current position of the cursor.

  - Ctrl A Edit Select All

  - Ctrl Z Edit Wrap Body — Cause all the lines in the message to be wrapped to the specified outgoing mail wrap column.

  - Ctrl R Edit Reflow Paragraph — Cause all selected lines to be wrapped to the specified outgoing mail wrap column.

  - Ctrl Shift R Edit Reflow Message — Cause all the lines in the message to be wrapped to the specified outgoing mail wrap column.

  - Ctrl Shift S Edit Check Spelling — Start spell checking the current message.

Show

  The Show menu is used to control which headers are displayed in the composer window for editing.

  - Show From — Display the `From` header.

  - Show Recipients — Display the `To:`, `Cc:`, and `Bcc:` addresses.

  - Show Reply To — Display the `Reply-To` header.

  - Show Fcc — Display the `Fcc` header; this is the folder to which your copy of the sent message will be saved.

Language

  The Language menu allows you to set the language to use for composing and checking the spelling of the message.

  The available languages include:

  - Brazilian

  - Catalan

  - Chinese (Simplified or Traditional)

  - Czech

  - Danish

  - Dutch

  - English (American or British)

  - Esperanto

  - Estonian

  - Finnish

  - French

  - German (including Austrian and Swiss)

  - Greek

  - Hebrew

  - Hungarian

  - Italian

  - Japanese

  - Kazakh

  - Korean

  - Latvian

  - Lithuanian

  - Norwegian

  - Polish

  - Portuguese

  - Romanian

  - Russian

  - Serbian (including Latin)

  - Slovak

  - Spanish

  - Swedish

  - Tatar

  - Turkish

  - Ukrainian

  and more may have been added.

Options

  - Options Request Disposition Notification — If checked &Balsa; will include the `Disposition-Notification-To` header line with your `From` address. Please note that the handling of this request depends on the receiving mail program and that it not guaranteed that this notification will be sent back.

  - Options Format = Flowed — The Flowed format (RFC 3676) breaks the message text into paragraphs, which you type continuously using the Enter key only to mark the end of a paragraph, and fixed lines which you mark individually using the Enter key. This allows other mailers that recognize the format to display the text appropriately for the width of the recipient's screen, and to quote the text correctly when constructing a reply. The text is also displayed intelligibly by a non-flowed-aware mailer.

    Using Format=Flowed is strongly recommended. It helps to avert the embarrassing line wrap that you see when quoted text is broken across lines and shown with the wrong level of quoting.

  - Options Send as plain text and HTML — &Balsa; can send and receive messages in right-to-left languages such as Arabic, Hebrew, and Persian, but some other agents such as mailing lists may mangle them when translating into HTML. If the Send as plain text and HTML option is selected, &Balsa; will generate a correct HTML message part that such agents will use instead.

  - Options Sign message — Cryptographically sign the message. The recipients can check the signature to prove the sender's (=your) identity or to detect any tampering with the message.

  - Options Encrypt message — Encrypt the message. Only the intended recipient(s) can decrypt and read the contents.

  - The following options determine the protocol used for signing and/or encrypting the message. You should choose the appropriate protocol which all recipients can use.

    - Options GnuPG uses MIME mode — Sign and/or encrypt the complete message, including all attachments, using the PGP/MIME mode (RFC 3156). Note that the message envelope (including the Subject) is not protected.

    - Options GnuPG uses old OpenPGP mode — Sign and/or encrypt only the message text, but not attachments, using the OpenPGP mode (RFC 2440). If you want to add any attachments, sign and/or encrypt them manually before adding.

    - Options S/MIME mode (GpgSM) — Sign and/or encrypt the complete message, including all attachments, using the S/MIME mode (RFC 2633). Note that the message envelope (including the Subject) is not protected.

    Cryptographic signatures and encryption are available only when &Balsa; has been built with &GnuPG; support. For a detailed description of E-Mail cryptography, see the GnuPG Manual and the GnuPG HOWTO.

### Toolbar

The toolbar contains buttons for the most commonly used functions when sending messages, including Send, Attach File..., and Save. As with the menu bar, some buttons are disabled if the message is not correctly setup to be sent.

Toolbar

Send

  Send the current message. Only available if the message is legal to be sent (i.e. proper email addresses). This button may also be configured to queue the message in the outbox to be sent later (see the Preferences dialog).

Attach

  Open a dialog to attach a file to the current message.

Postpone

  Postpone the message to the Draftbox for later revision and sending.

Check Spelling

  Start a spell check on the current message. If &Balsa; is built with support for GtkSpell, your spelling is checked in place. Otherwise, &Balsa; can use either ispell or aspell to do the spell checking. Settings for this can be found in the Preferences dialog.

Print

  Print out the draft of the message.

Cancel

  Close the composition window without saving or sending the message within.

### Headers

The headers area is where the information regarding where the message is being sent to and from, as well as comments and keywords can be entered. All of the available headers are not shown by default, but they can be turned on and off very quickly using the menu.

From

  `From` is used to indicate the origin of the message, &Balsa; automatically fills this in for you if you have entered your name and email address in the identities window.

To

  The `To` header is used to indicate the intended recipient of the message; &Balsa; automatically fills this in for you if you are replying to a message.

Subject

  The `Subject` header is used to summarize the topic of the message.

Cc

  The "Carbon Copy" header. A comma separated list of recipients other than the main recipient should go here.

Bcc

  The `Bcc`, or "Blind Carbon Copy" header. Similar to the Cc header, except that email addresses placed in this header will not appear as recipients to readers of the message. Also known as a "silent" carbon copy.

Fcc

  The `Fcc` header stands for "Folder Carbon Copy", and it is used to specify any folders that you want the message copied to after being sent. It is presented as a drop-down combo box with a list of all available mailboxes, simply select the destination.

Reply-To

  The `Reply-To` header is for specifying what email address you want any replies to go to.

Comments

  Although not widely used, the `Comments` header can be used to specify short comments for email's.

Keywords

  Again, not a very widely used header, this can be used to embed general information about the content of the message in the email, to allow for easier searching or filtering at a later date.

#### Specifying Addresses

&Balsa; supports many different methods of selecting email addresses. All of the headers that can contain addresses have a small colored book to the right of them that will open up &Balsa;'s address book.

However, &Balsa; will also attempt to guess what the headers should contain depending on what context the composition window is opened in, so it may not be necessary to fill them in most of the time.

Also, &Balsa; supports alias expansion. As you type a name, &Balsa; will guess the e-mail address from all the entries in the &GnomeCard; application. To enable this feature, read the section on Alias Expansion. In addition, the composition window supports drag-and-drop of addresses from the &GnomeCard; application.

### Attachments

List of Attachments

Below the headers may be a large box displaying a list of attachments; this view can be toggled in the Show menu.

When there are attachments displayed, it is possible to right-click on one of them to access an option menu. Inline and Attachment are mutually exclusive options that will display to the recipient either the attachment inline with the rest of the message, or separately as an attachment. Selecting Reference will send a MIME external part reference (a kind of link) in lieu of the actual file. Remove, and any available Open with options are also available.

### Message Body

Finally, below the attachment list is the main area of the window where the text of the message is displayed. The text editing capabilities are very basic, but it supports cut, copy, and paste so it is possible to write a message in your favorite editor and simply paste it in.

If the message is a reply or forward, the referenced message will be displayed in the body text widget, with the prefix specified in the Preferences dialog.

### Spell Checker

Once the spell check has been started, it will take a moment to load the text and spell checking module, and then it will automatically begin checking the message. If it finds any words that are incorrect, the word will be highlighted and a panel will be shown that offers a number of suggestions and available courses of action.

Spell Checking Panel

As shown above, the panel consists of a list of two panes, one the left containing a list of suggestions and an entry box, while the right contains several buttons to choose your action. The list on the left is re-generated for each incorrect word, with all the suggestions the spell check program comes up with. You can choose what program you want to use through loadable modules, selectable in the Preferences dialog. The entry box above the list is what will be used to replace the current word, and usually reflects the current selection in the list, but can be edited by hand if you wish to make manual changes.

The buttons on the left control the actions to take for each incorrect word. The buttons include:

Change

  Change the incorrect word with the currently selected suggested word or the user's edited word.

Change All

  Change all occurrences of the current incorrect word with the currently selected suggestion.

Ignore

  Ignore the current incorrect word and continue to the next one.

Ignore All

  Ignore all occurrences of the current word, and continue to the next incorrect word.

Learn

  Add the current incorrect word to your personal dictionary. This will cause it to be considered correct for all future spell checks.

Done

  Stop the spell check at the current point, keeping all changes so far and returning to the normal message window interface.

Cancel

  Stop the spell check at the current point, reverting all changes so far, including any words added to your personal dictionary.

### Address Book

When composing a message, clicking on any of the colored book icons next to a destination field (To, Cc, Bcc) will bring up the &Balsa; address book. It helps you to select recipients for your messages quickly and easily.

Address Book Window

The address book provides two panes, the one on the left consisting of all available addresses, while the one on the right contains the intended recipients of your message. Addresses are added to the recipient list by selecting them in the left pane and clicking the arrow button pointing to the right, or by simply double-clicking on the address. This will remove the address from the left pane, so they cannot be added more than once. If you decide that you no longer want to send the message to a particular address, simply select it in the right-hand pane and click the left-arrow button, or double-click it again, to move it back.

If, while selecting people to send your message to, you decide to add someone new to the address book, it is a simple matter to click on the Run GnomeCard button. This will bring up the &GnomeCard; application, allowing you to easily manipulate your contact list. After any changes have been made using the address book, they can be forced to show up in the left hand pane by clicking on the Re-Import button.

## The Message Window

In addition to the preview pane, &Balsa; can display messages in separate windows. Simply double-click on the desired message from the message index in the main window, or select the message and press the space bar. Any number of windows may be opened, although only one per unique message.

The message window has a menu and toolbar containing commands pertinent to an individual message. Commands are as described in the main window. Below the menu and toolbar are the message headers in a box, followed by the message body.

Message Window

If your copy of &Balsa; has cryptographic support, there will be an icon in the header box depicting an envelope with a lock and a check mark. Clicking the icon will check the key used to sign the message. The message body will contain an icon and some descriptive text noting whether the signing key is valid, invalid, or unchecked.

If the message contains attachments or more than one part of any kind, an attachment icon will be present in the header box as shown below. Clicking this icon will show a menu of all available parts. Selecting a part will update the display of the message body accordingly.

Selecting a Message Part

The complete message selection will do its best to render all parts at once, but some may have to be selected individually or opened in an external program. Parts which cannot be rendered within &Balsa; will instead display a list of options for opening external programs or saving the data. Right-clicking on a part will also provide a menu with these options.

Navigation between messages is possible without returning to the index in the main window. Next unread being quite useful for checking all new mail. Deleting the current message will automatically display the next unread one. This behavior can be changed in the preferences.

## The Preferences Window

&Balsa; has many more options than the initial assistant reveals. To access the Preferences window, select Edit Preferences . In the Preferences window, options are organized into groups, and related groups are shown on individual pages. The pages and groups are explained below.

## Mail Servers

This page lets you specify how you get POP3 mail, send mail, etc.

Remote Mailbox Servers

  These are &IMAP; and &POP3; servers that you receive email from. The three buttons let you create, modify, and remove records. &POP3; mailboxes will not show up in the mailbox list. You can specify multiple servers, when adding a server you will be asked to give:

  - mailbox name that will identify the mailbox

  - The server you have the POP mailbox on.

  - The port that will be used to connect to the server. The port number is usually 110 but you may change it if you for example use some kind of connection tunneling,

  - The user name on the mailbox server.

  - Corresponding password.

  - You can select the 'delete from server' button to remove the downoladed messages from the server.

  - You can choose to have messages filtered through procmail.

  - The procmail command.

  - Whether to check for new mail.

Local Mail Directory

  This is the directory that &Balsa; will scan looking for mail folders.

Outgoing Mail Servers

  Most users will need only one outgoing mail server, but you may need to use more than one. &Balsa; allows you to set up as many as you need. The server used for a particular message is controlled by the identity you choose for the message.

  To view or change the details of a server, select it and click Modify. To create a new server, click Add. A dialog will open, showing the properties of the selected server. Specify the domain name and optionally the port for of the SMTP server you use for submitting mail. Please note that the default port number is 587. The syntax is hostname[:port]. Port can be a decimal number or the name of the service as specified in `/etc/services`. Typically you can just set this to localhost:smtp. &Balsa; can also break up a large message into fragments, which can be reassembled by &Balsa; or any RFC 2046-compliant mailer. This dialog allows you to set this option, and the size above which a message should be split.

  You will be asked to give:

  - A descriptive name that will identify the server

  - The domain name and port

  - The user name on the SMTP server. If the remote SMTP server requires authentication, enter your user name here. Note that the exact format depends on the MTA in use. For example, some systems expect a user name, others may require an email address.

  - Corresponding pass phrase. If the remote SMTP server requires authentication, enter your pass phrase here. Some systems refer to the pass phrase as a password. Limitations on the length of the pass phrase depend on the SMTP server.

  - When you want &Balsa; to use TLS.

  - The TLS certificate pass phrase.

  - Whether to split large messages, and the threshold size.

## Incoming and Outgoing Mail

Use this page to set the &Balsa;'s behaviour regarding incoming and outgoing messages.

### Incoming

Check Mail Automatically

  If selected, &Balsa; will connect to your &POP3; servers at the given interval and check for mail.

Check IMAP mailboxes

  If selected, &Balsa; will include your IMAP mailboxes when checking for mail. You can also specify that INBOX is the only mailbox to be checked.

  Checking IMAP mailboxes can take some time; these options give you extra control over how long the mailbox check will take.

Display message if new mail has arrived

  If selected, &Balsa; will alert you when mail has arrived.

Do background check quietly

  If selected, &Balsa; will give you no indication that a background mail check is in progress.

Wrap Incoming Text

  If selected, &Balsa; will wrap text of incoming messages at the specified line length.

Reflow messages of type `text/plain;format=flowed'

  The `format' parameter distinguishes two ways of representing paragraphs in messages of type `text/plain' (that is, simple text). The value `flowed' indicates that paragraphs have been broken into lines ended with `soft' line breaks: a space is left at the end of the line. A `hard' line break (one that is not preceded by a space) indicates the end of a paragraph.

  &Balsa; can reflow the paragraphs, quoted or otherwise, in a message of this type. Reflowing eliminates the line fragments that are left when text is first wrapped at one length and then rewrapped to a shorter length, which are often misquoted.

  The only other value of `format' is `fixed', which is the value assumed by default when `format' is not specified, as with older mailers. In this case, all line breaks must be respected. If you do not select the `Reflow...' option, &Balsa; will treat all messages of type `text/plain' as if they were `format=fixed'. Long lines will still be wrapped, if the `Wrap Incoming Messages' option is selected, but this will usually leave unquoted line fragments.

Message Disposition Notification request

  You will sometimes receive a message whose sender has asked for notification that you have received or seen the message. You can specify how &Balsa; responds to these requests.

### Outgoing

Wrap Outgoing Text

  Have &Balsa; wrap all outgoing mail at the specified column.

Reply prefix

  The string that &Balsa; should use as a prefix when quoting a message. Note: When you send a message with format=flowed, &Balsa; is required to use the one-character string ">".

Automatically quote original when replying

  Have &Balsa; include the text of a message in the reply. The text will be prefixed as shown above.

  You can instead include the original message using an option on the `Edit' menu, or by dragging the message from the message index into the text area of the reply. If you prefer to include text this way, do not select the `Automatically quote...' option.

Don't include HTML parts as text when replying or forwarding mail

  Tell &Balsa; to be sensible.

Forward a mail as attachment instead of quoting it

  If this option is selected, messages that are `Automatically quoted' will actually be attached unmodified, instead of included in the text of the reply, prefixed by the reply string.

  You can also attach any message to a new message by dragging it from the message index into the attachment area of the new message (or, in fact, any part of the new message window except the text area or the address lines).

Send button always queues outgoing mail in outbox

  This option gives you control over when &Balsa; connects to a server to send messages.

Copy outgoing messages to sentbox

  Have &Balsa; save a copy of each message you send in the mailbox marked as the `Sentbox'.

Encoding

  Set the character encoding method to either 7 bit, 8 bit, or what the quoted message is using.

## Display Options

This page controls how &Balsa; appears to you.

### Main Window

Use Preview Pane

  Set whether to use the preview pane to display messages, or rely on the separate mail viewing window.

Show Mailbox Info

  This will allow the number of total and unread messages for each mailbox to be shown in the left pane of the &Balsa; main window. You can save space by not showing them; if you choose not to show them, &Balsa; will then show the number of unread messages (in parentheses) after the mailbox name.

Alternative Layout

  &Balsa;'s default layout has a full-height mailbox list on the left, and the message list above the preview pane on the right. You can choose an alternative layout, in which the mailbox list and the message list occupy the upper part of the window, and the preview pane is full-width below them.

Automatic View

  Select this option if you want &Balsa; to open the first unread message when you open a mailbox. If no message is unread, &Balsa; opens the most recent message.

Page Up and Page Down

  By default, the Page Up and Page Down keys scroll the message by whole pages. Use this option to choose a different amount.

### Message Window

Moving a Message

  If you are reading a message in its own message window and you move it (to the trash, or another mailbox), &Balsa; can move on the next unread message or the next message in the same mailbox, or simply close the window.

### Sort and Thread

Default sort column

  Choose the column by which you would like a new mailbox to be sorted.

Default threading style

  Choose the default threading style for a new mailbox.

Expand threads

  If you choose a threaded view of a mailbox, you can decide whether the threads should be expanded or collapsed when the mailbox is opened.

### Message

Fonts

  Choose the fonts that you want to be used to display a message. You can choose a distinct font for the message's subject line.

Quoted Text Regular Expression

  The entry box allows you to set a regular expression you would like to use to identify text that should be considered quoted for incoming messages. The regular expression should match the beginning of line of quoted text a single level deep, the program will then use this to calculate the depth of quoting and alter the quoted text colors appropriately. A default regexp is provided that should work in most situations.

  This regexp affects both highlighting and spell checking, and uses the extended regular expression set. For more information see the `grep`(1) manual or info page.

Alternative Parts

  You can choose whether &Balsa; should show a text/plain part or a text/html part, when a message contains both.

### Colors

Message Colors

  Choose the colors for quoted text.

Link Color

  &Balsa; uses this color to highlight a hyperlink in a message.

Composition Window

  When you are composing a message, &Balsa; uses color to show when one of the address fields is incomplete. Choose that color here.

### Format

Date Encoding

  Set the format used to display dates in &Balsa;. This uses the same format string as `strftime`, a summary which is provided below:

  - `%a` — The abbreviated weekday name.

  - `%A` — The full weekday name.

  - `%b` — The abbreviated month name.

  - `%B` — The full month name.

  - `%d` — The day of the month.

  - `%R` — The time using a 24-hour clock. (HH:MM)

  - `%r` — The time using a 12-hour clock (HH:MM AM/PM).

  - `%T` — The time using a 24-hour clock, with seconds (HH:MM:SS).

  See the `strftime` manual page for a full listing of conversion specifiers.

Selected Headers

  A space-separated list of the headers to display in the message window.

Fallback codeset

  Some messages contain national characters without specifying how they are encoded. You can choose whether &Balsa; displays such characters as '?', or tries a specific character set to display such messages.

### Status Messages

Information Messages

  &Balsa; gives you information in the form of five different levels of messages. You can specify how you want all five levels to be presented to you.

Display Progress

  This sets the behaviour of the dialog that is shown when &Balsa; retrieves messages from it's specified &POP3; servers. The dialog can be shown only while the messages are being retrieved, automatically closing after &Balsa; is finished. Or it can be set to stay active until manually closed. Finally, the dialog can not be displayed at all.

## Spelling

If &Balsa; is using GtkSpell, you can choose to have your spelling checked as you type. &Balsa; uses GtkSpell's default settings.

If &Balsa; is not using GtkSpell, you can use this pane to setup &Balsa; spell check options. &Balsa; uses the Portable Spell Checking library (pspell) to provide an interface to the spell checking program of your choice. Currently there are modules for ispell or aspell, both of which can be found at the pspell website. For more information visit the &Balsa; homepage.

Pspell Module

  The Pspell library allows you to use whatever spell checking engine you prefer, though the use of loadable modules. Currently Pspell has support for two modules, the traditional ispell, and the newer and more advanced aspell.

  Ispell is most likely available on your system as it is a Unix standard; however Aspell is more advanced as it uses an advanced phonetics engine and adaptive techniques to learn how you tend to misspell words. More information is available at the Aspell website.

  &Balsa; will attempt to use whatever module you specify here, however if the module is not installed it will not work and generate an error.

Suggestion Mode

  The suggestion mode determines how hard the computer will search for suggestions for misspelled words. There are three options:

  Fast

    This mode quickly scans for replacements, which means it might be used by a good speller who occasionally makes typographical errors.

  Normal

    The Normal mode is probably good enough for most people; it should produce the correct suggestion in the majority of cases.

  Bad Spellers

    The Bad Spellers mode is the most thorough and accurate mode; however, it also takes the longest to find a list of suggestions.

Ignore Length

  This provides the ability to ignore words shorter than a certain length. It may be useful to automatically skip short acronyms that are normally flagged as incorrect.

## Address Books

&Balsa; supports the use of multiple address books, both local VCARD and remote &LDAP; address books, both of which can be configured here. &GnomeCard; also uses VCARD address books, so this allows &Balsa; to share address books with other GNOME applications.

&Balsa; also supports LDIF address books, and can be built to use GPE address books, when SQLite is available. Which types are supported depends on how &Balsa; was built.

The main portion of the preferences page is occupied by the list of current address books for &Balsa;. The list shows the type of address book, the name, and whether it is included in automatic alias expansion when typing new messages. There are also several buttons that manipulate the list of address books:

Add

  Using this adds a new address book for &Balsa; to use to find addresses. If you click it, a drop-down menu of the supported address book types is shown. Click one to begin the process. &Balsa; pops up a dialog, which, if you choose VCARD, looks like this:

  VCARD Address Book Dialog

  With &LDAP; support, the dialog looks somewhat different, offering options to set the location of the directory instead of a file.

  &LDAP; Address Book Dialog

  In order to use a LDAP address book, you need to know the host name of the LDAP server. Depending on the server configuration, you may need also so called Base Domain Name which identifies your particular department. You can always try leaving Base Domain Name field empty and a default value will be used (OpenLDAP stores the default Base Domain Name in `/etc/openldap/ldap.conf`). If this does not work, you may need to ask your administrator for the value of this. The usual values are usually similar to: dc=theochem,dc=KTH,dc=se or o=Theoretical Chemistry, c=SE.

Modify

  This enables you to change the properties of the selected address book.

  Modify an Address Book

  It is possible to modify both the name and location for any address book. Also, you can change whether the contents of the address book will be used when attempting to auto-complete an address when sending a message.

Delete

  Delete the selected address book.

Set as Default

  Set the selected address book as default.

## Startup

Open Inbox upon Startup

  If set, &Balsa; will open your system inbox upon startup.

Check Mail at Startup

  If set, &Balsa; will automatically attempt to download mail from the &POP3; mail server upon startup, and will check for new mail on an &IMAP; server.

Remember Open Mailboxes Between Sessions

  When marked, &Balsa; will remember and reopen mailboxes that were open when &Balsa; was last quit.

Folder Scanning

  Scanning a folder tree can be time-consuming, because of the need to explore an entire tree of subfolders. You can defer scanning the tree by setting the scan depth to 1. &Balsa; will then descend into the tree only far enough to discover whether any folders that you can see have subfolders. The first time you expand any subtree, &Balsa; will explore more of the tree.

  If you prefer to have the whole tree available from startup, choose a depth as great as that of your folder tree. Intermediate settings may also be used.

  You may set the depth for initial scanning separately for local and &IMAP; trees.

## Miscellaneous

Debug

  Toggle the output of debugging information. Depending on what notification priority set for it in the Display page, it can show up in list or dialog as the program runs.

Empty Trash on Exit

  Set &Balsa; to delete all messages in the Trash mailbox when &Balsa; exits.

Automatically close mailbox

  Set &Balsa; to close any mailbox that is unused for more than the specified time. The currently displayed mailbox is never automatically closed.

Hide messages marked as deleted

  When a message is moved to another mailbox, including the Trash mailbox, it is actually copied to the destination, and the original is marked as deleted. Deleted messages may either be shown in the mailbox index, with the trashcan icon indicating that they are deleted, or hidden. This item controls which of those actions is taken.

  A message may also be simply marked as deleted, without copying it to another mailbox: Message Toggle flag Deleted . Again, this item controls whether such a message is hidden.

Expunge deleted messages on close

  Expunging is the act of physically removing from the backing mailstore all messages marked as deleted. You can expunge messages manually: Mailbox Expunge deleted messages , or you can set &Balsa; to expunge deleted messages when the mailbox is closed (all mailboxes are closed when you exit &Balsa;).

## Customizing Toolbars

&Balsa; allows you to change the layout of the toolbars on the three main types of window: the main window, message windows, and compose windows. You open the dialog with the Settings Toolbars... menu item.

The dialog contains a notebook with a page for each type of window. On each page, you'll see a Preview of the toolbar, which changes as you change the layout. The list of Available buttons shows buttons that may be used on the toolbar, but aren't currently used, and the Current toolbar list shows the current layout, including both buttons and separators. You can add buttons to the current toolbar, remove them, or move them up or down in the list, using the controls in the central button box.

Below the notebook is a checkbox for wrapping the button labels (the text that may accompany the buttons). This option applies to the toolbars on all three types of window. If you choose wrapping, long labels will be shown on two lines.

This is an instant apply dialog: the changes you make take effect immediately, as shown in the Preview toolbar. Below the Preview toolbar you'll find a button that restores the standard layout for that toolbar. Note that the standard layout is the one that you see before the toolbar has been customized. If you use this option, all current and past changes will be undone.

A second button below the Preview toolbar pops up a menu that gives you control over what is shown in the toolbar: icons, text, or both. The popup (right click) menu for any actual toolbar offers the same choices, as well as the option to open up this dialog (Customize Toolbars...).

## IMAP Folder configuration

The folder configuration edit dialog allows you to configure entire mailbox sets on remote IMAP servers. Entire configuration is split into basic and advanced parts.

### Basic IMAP folder configuration

The basic IMAP folder configuration tab is probably the only part you need to fill in.

- Descriptive name is the name of the root node that will be shown in the mailbox tree on the left side.

- Server is the host name or IP number of the IMAP server.

- User name is the name used for authorization on the IMAP server.

- Some servers allow anonymous access to bulletin boards or mailing list archives. Check this box if you want to use this mode - you will not be asked for password.

- Password is the password used for authorization on the IMAP server.

- Check box allows you to choose all mailboxes on the server, or only those you subscribed to.

- Prefix is the root mailbox on the server. You may leave it empty if you want to show all the folders on your server but if your IMAP server stores also other kind of files you may specify for instance "mail".

### Advanced IMAP folder configuration

Sometimes, it is necessary to tune the folder configuration in order to assure a secure connection, adjust to server limits or just obtain better performance. This functionality is provided by the Advanced IMAP folder configuration tab.

- The Use SSL check box should be active if the connection is to be made to IMAPS service on port 993. Connection to this port will be encrypted from the start. Not all servers provide this service - many provide only negotiated TLS encryption.

- The Use TLS option list determines instruct balsa how to negotiate the TLS encryption. &Balsa; can never attempt to negotiate it, can start TLS encryption whenever it is supported by server, or can abort the connection if TLS is unavailable or fails for some reason.

- Max. number of connections limits the number of concurrent connections open to the IMAP server. A number around 15-40 is a sane option as it avoids time-consuming and load-creating reselections of imap mailboxes. Some IMAP servers -- notably Courier -- limit the number of connections open from single IP number to 4 by default. The limit in balsa has to be in such a case adjusted accordingly.

- The Enable persistent cache check box chooses whether &Balsa; should try to store downloaded messages between sessions or throw them away when it is closed. The optimal choice depends on the local configuration. If the connection to the IMAP server is slow and local storage in the home directory fast and cheap, it is recommended to enable persistent message cache. If the home directory is slow (eg. NFS-mounted) and the connection to the imap server - fast, persistent cache becomes just a burden and should be disabled.

- The Use IDLE command check box chooses whether &Balsa; should try to use IDLE command when available. With this command, some servers notify immediately when a new command arrives. Also, this command may reduce the amount of network traffic. There are some downsides, too: some firewalls do not track IMAP connections correctly and will incorrectly interrupt a session in an IDLE state. In particular, home-grade network routers with NAT translation have notoriously this bug. In such case, it may be safer to disable this command.

- The Enable bug workarounds check box makes &Balsa; work even with IMAP server that cannot fail to provide selected message parts. &Balsa; in such a case will try to fetch entire messages instead.

- The Use STATUS for mailbox checking check box enables a more thorough but potentially more expensive way of checking mailboxes on IMAP server. This method can be consume many resources on the server and should be used only on IMAP servers that have optimized STATUS command.

### IMAP Subfolder Properties

The subfolder properties dialog allows you to manage folders on remote IMAP servers. Specifically, you can create a new subfolder, rename an existing subfolder, or move a subfolder within the folder tree.

- Folder name is how the folder is shown in the mailbox tree on the left side.

- Subfolder of indicates the immediate parent of the folder.

When the dialog is opened from File New Remote IMAP subfolder , you can enter the folder name and browse IMAP trees to find the parent folder. If you had already selected a mailbox in an IMAP tree, only that tree is shown for browsing; otherwise, all IMAP trees will be shown.

When the dialog is opened from Mailbox Edit with an IMAP folder selected, or by right-clicking on an IMAP mailbox and selecting Properties..., the mailbox may be:

- Renamed, by editing the folder name;

- Moved, by browsing for a different parent folder in the same tree.

## Address book configuration

This is to be filled in.

### Address book type

You can choose among several address book types.

### External address book

The balsa addressbook supports input from programs. Thus, you can use (no importing needed!) for example your pine or mutt addressbook. The mutt mailer (www.mutt.org) uses an identical system to retrieve addresses from programs.

#### Existing programs

The following programs are compatible with the mutt mail reader and /should/ be with balsa. Submit links to more programs.

- http://www.spinnaker.de/lbdb/ - The little brother database. Read emailaddresses and names from: finger, /etc/passwd, incoming procmail email, NIS, fido, the abook program, mutt addressbook, pine addressbook, palm addressbook, gnomecard addressbook, big brother database, ldap database.

- http://www.fiction.net/blong/programs/mutt/ - palm address database, ldapsearch wrapper, ph/qi server, UIUC, ph,

#### Writing your own load scripts

&Balsa; ignores the first line of output from your program. You might want to write comments or debug output on this line. The remaining lines should have this format:

`e-mail address full name nickname`

The three fields should be separated by tabs. The third field is currently not used by balsa, but might be in the future. It is also kept to ensure compatibility with mutt.

&Balsa; executes your script with one argument: the pattern to search for. A space (" ") is used as the first argument when creating a list of all users.

All characters are allowed, except the tab (\t), since that is the field separator.

An example output could be:

`lbdbq: 3 matches`

`balsa-list@gnome.org Balsa List balsa-list`

`jelmer@nl.linux.org Jelmer Vernooij jelmer`

`balsa-maintainer@theochem.kth.se Pawel Salek balsa-maintainer`

Your script/program should write it's output to stdout and not to stderr!

#### Writing your own save scripts

Adding addresses is also possible. Your script should receive 3 arguments. The first is an email address, the second a full name and the third is an alias (currently not used and replaced by 'TODO').

Note that mutt does not have support for adding addresses and there is thus no compatibility in this case.

Comments are welcome: jelmer@nl.linux.org

## Identities

This dialog window lets you specify how you present yourself to the rest of the world through your email. The first page has your general information:

Identity Name

  A unique title by which this identity will be named within &Balsa;.

Full Name

  This doesn't have to be your name, I guess. But it's the word prefixing your email address in mail you send.

Mailing Address

  As you wish it to appear in your "From" header.

Reply-To address

  The address that you wish people to reply to your email with (if you have a home and a work address, for instance).

Default Domain

  The domain that you wish to append to all e-mail entries where you did not specify the domain. Normally you would use your local domain. You need to enable Alias Expansion for this to work.

The Messages page shows various initial settings for the new message:

Bcc

  The default value for the blind-carbon-copy field when using this identity. Useful if you want to always send a copy of outgoing mail to another account.

Reply String

  The prefix for the subject line when replying to a message.

Forward String

  The prefix for the subject line when forwarding a message.

Request Message Disposition Notification

  Whether Message Disposition Notification should be requested by default.

Face Path

  Whether a "Face" header should be attached to a program. Specified path points out to a file containing a textual representation of the face icon. Please see a description of Face and X-Face headers for more details as well as the list of mail programs supporting this feature.

X-Face Path

  Whether a "Face" header should be attached to a program. Specified path points out to a file containing a textual representation of the face icon.

SMTP server

  The SMTP server to be used for this identity.

You control the signature that &Balsa; appends to your messages on the Signature page:

Signature Path

  The file containing the signature to append to all your messages. This can be generated in one of three ways:

  - From a regular file. List the path to any regular file, and the text from that file will be appended to your messages.

  - A named pipe or FIFO. In this case, to &Balsa;, the file looks normal, but in reality, it is a pipe to a program that is generating the content. List the path to the pipe.

  - An executable program. &Balsa; will execute the program and read its output, appending that text to the message. List the path to the program with a | prepended to it. For example:

    |/home/user/dynsig.pl

Execute Signature

  Execute the instructions in the signature file and use the results as the signature to append to outgoing mail. Select this when generating the signature from an executable program as outlined above in Signature Path.

Include Signature

  Append the signature to the end of all outgoing mail.

Include Signature When Forwarding

  Add the signature when forwarding an existing mail.

Include Signature When Replying

  Add the signature when replying to a existing message.

Add Signature Separator

  When checked, this has &Balsa; insert the standard signature separator before your signature.

Prepend Signature

  Add the signature before the message text, rather than after it.

Security settings are on the fourth page:

Sign messages by default.

  By default enable the cryptographic signature for every new message. The default protocol is determined by the Default protocol option.

Encrypt messages by default.

  By default encrypt every new message. The default protocol is determined by the Default protocol option.

Default protocol.

  Choose the default protocol for the cryptographic signature and message encryption.

Always trust GnuPG keys when encrypting.

  Do not ask for confirmation when encrypting for a recipient whose GnuPG key is not fully trusted.

Remind me if messages can be encrypted.

  Before sending a message, check if valid keys are present for all recipients and show a dialog in this case.

Use secret key with this id for signing.

  Usually, &Balsa; automatically selects a proper secret key for cryptographic signatures from the identity's mail address. Therefore, most users should leave this entry empty. If you want to force using a specific secret key for cryptographic signatures, enter the key id here. You can get the key id by running the command 'gpg --list-secret-keys'.

These security options are available only if &Balsa; is built with GnuPG support.

## The Search Mailbox Window

You can search a mailbox to find and display messages that contain a given string in the To, From, Subject, or Cc headers, or in the message body. This window allows you to specify the string for which you want to search and where &Balsa; should look.

You can view the matching messages in two ways:

Show only matching messages

  If you click the Apply button, the mailbox view will be filtered to show only the messages that match the conditions. If you click the Clear button, the filter will be cleared, and the mailbox view will be restored to show all messages. You can also use Mailbox Reset Filter to restore the view.

Open next matching message

  Alternatively, you can step through the matching messages, either forward or in reverse, and optionally wrapping the search when it reaches the end of the mailbox. Click the OK button to view the first matching message after (or before) the current message. Then you can use Ctrl G Edit Find Next to step through the matching messages.

## The Filters Window

This window is divided in two parts: the left part is the list of all filters. When you select one of them, the right part displays its properties. The right part is a two-page notebook (the match page, and the action page); their descriptions follow.

There are two buttons under the filters list:

- The New button: you click on it to create a new filter; the filter is initially named "New Filter", and contains no condition. Then you fill in the different fields in the notebook pages (in particular remember to change the name of the filter), add the conditions that will describe how this filters matches a message, and to confirm the modifications push the Apply button on the right hand side of the Filters window.

- The Remove button: removes the currently selected filter.

### The match page

Each filter is made of one or several conditions; each condition represents a test to be applied to the messages. The results of these tests is then combined following the type of operation specified:

- AND: all condition tests must be true to make the match.

- OR: one condition test must be true to make the match.

Then the page displays the name of the filter and the conditions that describes how the filters matches a message. The list displays the type of the conditions (the conditions will be described later):

- Simple: the match is done by a simple substring test.

- Regular expression: the match uses regular expressions on the message headers.

- Date interval: the match is done by checking if the date of the message is within certain bounds.

- Flag condition: the match is done by checking the flags of the message: unread, replied, deleted, flagged.

The three buttons under the list allows you to edit the selected condition, add a new one, or remove one. Editing or creating a condition is done in the condition window, which pops up when you click on the Edit or the New button.

The two buttons under the notebook at the right hand side of the window lets you manipulate the currently selected filter. The Apply button is used to confirm the modifications you have made on any field. If you make changes and select another filter without first clicking on the Apply button, all your changes will be lost.

The Revert button cancels all previous changes: the current filter is reverted to its state just before the last click on the Apply button.

### The action page

This page describes the actions to take in case the filter matches. First you specify the notification to inform you that the one or several messages has matched the filter in the Notification frame. Then in the Action frame you tell what to do with the matching messages. You can ask &Balsa; to copy or move them to any mailbox, or to send them to the trash can. The other actions are not yet implemented.

### The condition window

This window is used to edit an existing condition or to create a new one. It displays all the information needed to describe the condition, it is launched when you click on the Edit or New buttons under the conditions list in the match page of the notebook in the right part of the filters window.

This window is made of three frames:

- The Match in frame: it's a set of check boxes, one per match field. For example if you want to match all messages that was sent by hotmail users, you just have to check the From box, or if you want to match all messages about &Balsa;, check the Subject box.

  Be careful with Body match, this can take time for large messages.

  For advanced use you can also specify directly the name of the header to match on. A standard example the "X-Mailer" is a header added to your message by the MUAs with their name and versions.

  The All button will check all boxes, whereas the Clear button will uncheck all boxes (as you might have guessed).

  If you specify several headers, a message will match this condition if one of the header matches. For example if you want to filter all messages talking about &Balsa;, you should check the Body and the Subject boxes, so that all mails with the word Balsa in its subject or its body will match. You can also, if you're fed up with &Balsa; ;-), match all mails that do NOT contain the word Balsa in their subject and in their body neither. See the description of the search types to see how to do this.

- The Search Type frame: it's a list of the different condition types. You choose Simple, Regular expression, Date interval, or flag condition. Your choice will change the third frame so that it displays the fields needed by the type of match chosen.

- This part depends on the search type you've chosen:

  - Simple type: a text entry lets you input the string to look for (case does not matter, the search is case-insensitive). The button lets you specify if a message matches when the string is or is NOT a substring of the specified headers, the sentence above the text entry will be updated accordingly.

  - Regular expression: you can input a list of regular expressions. You type your regular expression in the text entry, then you click on the Add button to put it into the list. Of course the Remove button destroys the selected regular expression in the list. The last button One matches/None matches lets you specify when a message matches the condition: when one of the regular expression matches or when none matches. The sentence above te list will be updated accordingly.

  - Date interval: you can input the interval by the mean of the two text entries. A blank entry means no bound. The button tells to match when the message date is within the bounds or not. The sentence above the text entries will be updated accordingly.

  - Flag condition: the four check boxes let you select which messages will match this condition. If you want to match all replied OR unread messages, check the corresponding boxes. The button let you specify that the match will be done when none of the specified flags are set, the sentence above the check boxes will be updated accordingly. For example if you want to filter all read and replied messages, check the unread and replied boxes, and click on the button.

## The Select Filters Window

This window is divided in two lists: the left one displays all available filters, and the right part displays all filters to be applied on the mailbox (the name of which is shown in the window title). See the filters window section to see how to set up filters.

The right list has three columns. The first one contains the filters name. The two others tells you if the filter will be automatically applied: e.g. if a dot is displayed in the second column (On reception), this tells you that whenever new messages arrived in this mailbox, they will be filtered by the corresponding filter (Note: the filter is applied only on the new messages, not the entire mailbox; this is similar to the use of procmail). In the same way, if a dot is displayed in the third column (On exit), the filter will be applied to the entire mailbox when you exit &Balsa;.

Note: the On exit feature is not yet implemented.

When you tell &Balsa; to apply several filters on the same mailbox (i.e. when you put several filters in the right list), only the first match counts: the filters are applied in the specified order and the first that matches on the current message will be applied but not the following ones.

There are two buttons between the filters lists:

- The Add button: moves the selected filters from the left list to the right one, adding more filters to be applied to the mailbox.

- The Remove button: removes the currently selected filter in the right list and puts it back in the left list.

The Up and Down buttons under the right list serve to reorder the filters that are to be applied. This is a sort of priority between filters, because if several filters could match the current message, only the first one will be applied. The Apply Now button applies all filters of the right list to the entire mailbox immediately (be patient, this can take a quite a long time on big mailboxes or remote ones).

You can also use this dialog to apply a filter to a mailbox without actually attaching it to the mailbox. Select one or more filters in the left hand list, and click the Apply Selected button below that list.

There are three buttons below the filters lists:

- The OK button: saves the list of filters associated to the mailbox. Note that this does not apply the filters to the mailbox. It is useful only when you have set up automatic filters, or when you have to manually apply a lot of filters frequently to this mailbox: the next time &Balsa; will reload the saved filters and you will only have to press the Apply button.

- The Cancel button: this discards any changes and closes the dialog box.

- The Help button: opens this help window.

## Available mailbox formats

&Balsa; handles several mailbox formats, including mbox.

The further information can be found in the following documents:

- Benchmarking mbox versus maildir http://www.courier-mta.org/mbox-vs-maildir/

- Mailbox Format Characteristics http://www.washington.edu/imap/documentation/formats.txt.html

- maildir(5) manual page (from qmail) http://www.qmail.org/qmail-manual-html/man5/maildir.html

- Using maildir format http://cr.yp.to/proto/maildir.html

- mbox(5) manual page (from qmail) http://www.qmail.org/qmail-manual-html/man5/mbox.html

- Mailbox formats (from Mail-Administrator HOWTO) http://linuxdocs.org/HOWTOs/Mail-Administrator-HOWTO-3.html#ss3.5

## Common Tasks with &Balsa;

This section explains many of the things you might want to do with &Balsa;.

- Creating new mailboxes

- Moving messages around

- Making one of the main folders IMAP-based

- Expanding e-mail addresses automatically

- Setting up LDAP address books

### Creating New Mailboxes

You can create new local and IMAP mailboxes by right-clicking in the mailbox list and selecting New Mailbox. This will start a dialog that will let you name the mailbox and specify its location.

To create a new &POP3; mailbox, go to the configuration dialog, select the Mailboxes section, and click Add in the POP3 area. A dialog will be displayed that will let you set up the new mailbox.

Under Sawfish, this dialog has been known to become obscured, causing the appearance that &Balsa; has locked up. Move the configuration dialog and see if the new dialog was hidden.

### Moving Messages

There are several methods available for moving or copying messages from one mailbox to another. The first is via the Transfer context menu, and the second is using drag and drop.

To transfer messages using the Transfer menu, simply select the messages you desire to move from one mailbox, then bring up the context menu and select the Transfer submenu. This will display a list of mailboxes similar to the mailbox list in the main window. The list can be scrolled and trees expanded and collapsed, although these changes will not be reflected in the main list. Selecting a mailbox will start the transfer.

The other method of transferring messages is to simply drag and drop the message(s) from the message index to the desired destination. Select the message(s) you wish to transfer, then drag them using the mouse until they are over the intended mailbox. The destination can either be in the mailbox list in the main window, or if open mailbox tabs are enabled the messages can be dragged to them. Messages are copied by default, but holding down the Shift key when dropping the messages will move them instead.

### I want one of the main folders to be IMAP

First, create the IMAP folder as you want it configured. Then, press right mouse button on the mailbox entry and select Mark as Inbox. That is all!

### I want Balsa to guess my friends

&Balsa; can expand the names of your contacts it finds in &Balsa; addressbooks. It will do this by any part of the contact's name or email address.

As you type a username in any of the To:, Cc:, or Bcc: entry boxes in the Compose window, it will do a case insensitive search in the addressbook for a matching username, and pop up a list of matching complete addresses. Press Cursor-Down to highlight one of the addresses, and Enter to select it.

To enable this feature, you must select which address books you wish to be searched for aliases to expand. This can be done in the Preferences window, on the Address Books page. Also, some address books are expensive to lookup. You will need then to press Escape to explicitly expand the alias.

### Setting up LDAP address books

Only steps crucial for &Balsa; are described here. Some of the steps may be specific to OpenLDAP server. Whenever in doubt, consult the documentation provided with your LDAP server.

- Install the LDAP server software.

- Configure. In the case of OpenLDAP, edit `/etc/openldap/ldap.conf` and `/etc/openldap/slapd.conf`. Consult your LDAP configuration and other sources to choose the right Domain Name for your institution and authentication level appropriate to your environment.

- Import data to your LDAP server. OpenLDAP comes with a set of migration tools but they do not create directly objects of standard inetOrgPerson class which is an appropriate type for address book entry. You may need to tune them.

&Balsa; searches for objects having mail attribute. The search is done on the cn attribute and the search filter has a form (&(mail=*)(cn=John D)). &Balsa; uses cn (common name), givenName (given name), sn (surname) and mail (e-mail address) attributes of the found objects.

## It's not Working!!!

This is a FAQ for when &Balsa; appears to lock up, or other things that you think should be happening aren't. If you can't figure out how to do something but &Balsa; lets you do it, that's a bug. Report it.

- I want one of the main folders to be IMAP

- &Balsa;'s frozen!

- What's that window that flashed on the screen?

- The address book doesn't import my addresses.

### I want a basic mailbox to use IMAP

See this section.

### &Balsa;'s frozen!

Odds are it isn't. Watch out for:

- If you don't have threading, &Balsa; will stop responding when it sends and receives email. Use threading, if possible.

- &Balsa; is downloading a new message or closing a large mailbox. This could take a while, especially when this file is accessed via NFS.

- A dialog box is being displayed but it is obscured by another one. This seems to happen under Sawfish. Try moving the windows around and see if there's a hidden dialog somewhere.

### What's that window that flashed on the screen?

Were you checking your mail? Probably. This is the window that displays progress for retrieving &POP3; mail. If you don't have any &POP3; accounts, it will still appear -- but it'll disappear almost instantly. You can disable displaying this window in preferences.

### The address book doesn't import my addresses.

&Balsa; attempts to open the file `~/.gnome/GnomeCard.gcrd`. If you're not using this file, you may need to create a symlink so that &Balsa; can open it.

There have been slight changes in &GnomeCard;'s file format between its various versions. &Balsa; is known to work with at least &GnomeCard; version 1.0.10 and probably most other releases.

## Authors

&Balsa; is currently developed by (in alphabetical order):

- Carlos Morgado (chbm@chbm.nu)

- Pawel Salek (pawsa@theochem.kth.se)

In the past, numerous people contributed to balsa, including (in alphabetical order):

- Hector Garcia Alvarez (hector@scouts-es.org)

- Matthew Guenther (guentherm@asme.org)

- Bruno Pires Marinho (bapm@camoes.rnl.ist.utl.pt)

- Jay Painter (jpaint@gimp.org)

- Stuart Parmenter (pavlov@pavlov.net)

- David Pickens (dpickens@iaesthetic.com)

- Peter Williams (peter@newton.cx)

Please send all comments, suggestions, and bug reports to the GNOME bug tracking database. Instructions for submitting bug reports can be found on-line at https://wiki.gnome.org/GettingInTouch/BugReportingGuidelines.

The following people contributed to this manual:

- Peter Bloomfield (peterbloomfield@bellsouth.net)

- Matthew Guenther (guentherm@asme.org)

- Craig Routledge (webstuff@craigroutledge.com)

- Berend De Schouwer (bds@jhb.ucs.co.za)

- Pawel Salek (pawsa@theochem.kth.se)

- Peter Williams (peter@newton.cx)

- Jelmer Vernooij (jelmer@nl.linux.org)

Please send all comments and suggestions regarding the manual to the GNOME Documentation Project at GNOME Discourse and the &Balsa; Discussion forum on GNOME Discourse.

## Glossary

POP

  An acronym for "Post Office Protocol", a simple method of retrieving mail messages from a remote mail server. Widely used by mail clients from an Internet Service Provider's mail server to a user's machine for viewing. Currently most people use version three of the protocol, otherwise known as POP3. A very simple protocol, and not very flexible, but simple to implement and ubiquitous throughout the internet.

IMAP

  An acronym that stands for "Internet Mail Access Protocol". It is a newer method of accessing mail over the internet. It is far more featureful than &POP3;, allowing for remote folders on the mail server, and more control over mail delivery. However it is not as widely supported.

LDAP

  An acronym for "Lightweight Directory Access Protocol". It is a widely-accepted standard for accessing contact information over a network. This enables organizations to store address information in a central database, but have many people able to access it.

libmutt

  The library based on Mutt's code and used by previous versions of &Balsa; to handle local mail and IMAP servers.

mailbox list

  The list of mailboxes found in &Balsa;'s left hand pane.

message index

  The list of messages in &Balsa;'s upper-right hand pane.

message view

  The message display in &Balsa;'s lower-right hand pane.

MDA

  An acronym for "Mail Delivery Agent", this type of program is also known as a Local Delivery Agent (LDA). It is responsible for delivering the mail received for someone on a machine to the mail folder of that person. &procmail; is an example of this type of program, although many MTA's have their own MDA implementations.

MTA

  An acronym for "Mail Transfer Agent", this class of program is responsible for moving mail around between people, be they on the same computer, on on completely separate networks. Examples of this type of program include sendmail, qmail, and postfix.

MUA

  An acronym for "Mail User Agent", this the program a user would use to read existing mail and create new messages. MUAs are one of three types of programs that allow internet email to work. The other two types of programs are MTAs and MDAs. &Balsa; is primarily an MUA, but it also functions as an MDA/MTA when retrieving mail from a remote server.

Regular Expression

  Often abbreviated as a regexp, this is a method of specifying a pattern to match in text. Both very simple and very complex patterns can be easily matched using this method. For information on how to understand and construct regular expressions the best source is the grep manual or info page.

SMTP

  An acronym that stands for "Simple Mail Transfer Protocol", it is exactly that. A standard that defines a simple an reliable way to transfer messages between computers on a network. It is used by most, if not all, mail programs to transfer mail.

VCARD

  VCARD is a standard method of storing contact information for easy exchange between programs. &Balsa; supports VCARD addressbooks, as does GnomeCard and Evolution. Many other programs are capable of exporting their contact lists in VCARD format as well.