1997-2001 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. &Balsa; is a graphical mail client similar to Eudora on Windows. 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. It is based on libmutt, the back end code to &Mutt;, but expands far beyond being a graphical Mutt. If you want to learn more about &Balsa;, your best bet is the mailing list balsa-list@gnome.org, which can be subscribed to by going to the website &balsalist; or by sending a message with a subject of subscribe to balsa-list-request@gnome.org. Bugs can be reported via bug-buddy, gnome-bug or to submit@bugs.gnome.org. If you're starting &Balsa; for the first time, the first thing you'll see is a Druid 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; or &POP3; mailboxes later.)

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.

&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; or &POP3; 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. (The other mailboxes will not have their contents probed.) Also, any mailboxes that contain unread messages will be shown in a different font and colour. At the top-right is a view of the currently open mailbox. 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 listing. You can save attachments, view attachments, and read incoming email here.

The menu bar, located at the top of the Main Window provides the following commands: File This menu contains basic commands. FileNew 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. CtrlM File Get New Mail — This causes &Balsa; to attempt to retrieve any new messages from the &POP3; server. CtrlA File Send Queued Mail — Send all mail waiting in the Outbox mailbox to the mail server now. File Print — Print the currently selected message (displayed in the preview 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. 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. 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. F Message Forward... — Forward the currently selected message(s). 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. CtrlS Message Save Current Part... — Save the currently selected part of the message to disk. D Message Delete — Delete the currently selected message(s). U Message Undelete — Undelete the currently selected message (currently non-functional). X Message Toggle Flagged — Toggle the flag on the currently selected message(s). This is shown as an exclamation mark next in the message index. S Message Store Address... — Add the sender of the currently selected message to your address book. 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. CtrlN Mailbox Next Unread — Select the next unread message in the current mailbox. Mailbox Edit... — Edit mailbox properties. Mailbox Delete... — Delete the currently selected mailbox. Mailbox Commit Current — Synchronize changes between the currently selected mailbox and the mailbox file on disk. Mailbox Close — Close the currently selected mailbox. Mailbox Empty Trash — Delete all messages from the Trash mailbox. Mailbox Edit/Apply 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 messages with duplicate message-IDs. If one of the duplicates is marked as `replied-to', that one will be retained. No attempt is made to verify that the messages really are duplicated. You could leave deleted messages visible, and check individually that the correct ones have been deleted. Settings Menu for changing &Balsa;'s configuration. Settings Preferences... — Open the Preferences window to change the settings of &Balsa;. 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 displays the messages in the current folder, and lets you choose which folders messages to view. Click on the notebook tabs, 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 Transfer menu item). Double-clicking on a message will open it 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 the currently selected message(s). Reply To All Reply to the currently selected message(s), sending the reply to all the recipients and senders of the message. Forward Forward the currently selected message(s). Move To Trash Deletes the currently message(s). Store Address... Store the sender of the current address in the address book. Toggle Flagged Toggle the priority flag on the currently selected message(s). This is shown as an exclamation mark in the message index. Transfer Transfer currently selected message(s) to another mailbox. When this menu item is selected a list of available mailboxes is displayed from which the destination should be selected. The message view displays the message that is selected in mailbox 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 the different sections will be shown below the main message text. Each part can be selected and &Balsa; will attempt to display it. If it is unable to it will display a screen allowing you to save the attachment to a file. Currently &Balsa; only supports viewing HTML messages when compiled with gtkhtml support. gtkhtml support is fairly stable nowadays and will be compiled in if gtkhtml-devel files is found. You are not restricted to that pane either. Double-clicking on a message in the message index will open it in a separate 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. In the near future, it will be possible to perform signing and encryption of messages using GnuPG or PGP. 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: 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. (does it depend on "Always queue sent mail?"). dialog. 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 Print... — Print a hard-copy of the current message out. CtrlW File Close — Close and discard the current message. A message is considered valid (ready for sending) if it contains only legal email addresses in the To: field. Edit The Edit menu contains commands which are used to modify the body of the message. CtrlX Edit Cut — Cut the selected text to the clipboard. CtrlC Edit Copy — Copy the selected text to the clipboard CtrlV Edit Paste — Paste the contents of the clipboard to the current position of the cursor. CtrlA Edit Select All CtrlZ Edit Wrap Body — Cause all the lines in the message to be wrapped to the specified outgoing mail wrap column. CtrlR Edit Reflow Paragraph — Cause all the lines in the paragraph the cursor is in to be wrapped to the specified outgoing mail wrap column. CtrlShiftR Edit Reflow Message — Cause all the lines in the message to be wrapped to the specified outgoing mail wrap column. CtrlShiftS 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 To — Display the To header. Show Subject — Display the Subject header. Show Cc — Display the Cc header. Show Bcc — Display the Bcc header. Show Fcc — Display the Fcc header. Show Reply To — Display the Reply-To header. Show Attachments — Display the Attachments box. Show Comments — Display the Comments header. Show Keywords — Display the Keywords header. Language The Language menu allows you to set the language to use for the composing the message. Currently, &Balsa; does not support multiple character sets in a single message. The current language in use is shown at the bottom of the menu, along with the character set in use. The available languages consist of: Baltic Brazillian Catalan Danish Dutch English Estonian Finnish French German Greek Hungarian Italian Japanese Korean Norwegian Polish Portugese Russian Slovak Spanish Swedish Turkish Ukranian 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. 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.

Send Send the current message. Only available if the message is legal to be sent (i.e. proper email addresses). 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. Balsa can currently use either the standard ispell or the newer 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. 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 identites 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. &Balsa; supports many different methods of selecting email addresss. All of the headers that can contain addresses have a small coloured 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 neccessary 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 addtion, the composition window supports drag-and-drop of addresses from the &GnomeCard; application.

At the base of the message composer window may be a large box displaying attachments; this view can be toggled in the Show menu. They show up as small icons that look like a piece of paper, with the name of the file displayed beneath them. When there are attachments displayed, it is possible to right-click on the icon to access a menu to manipulate the menu. Currently it is only possible to remove it from the message. 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. 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.

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 occurances 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 occurrances 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. When composing a message, clicking on any of the coloured 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.

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. To be filled in. &Balsa; has many more options than the initial Druid reveals. To access the configuration window, select Settings Preferences. You will see a notebook. The tabs and options are explained below.

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. What does the check check box mean? You can select the 'delete from server' button to remove the downoladed messages from the server. Local Mail Directory This is the directory that &Balsa; will scan looking for mail folders. Remote SMTP 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. User 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. 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. &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. 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. It brings up a series of dialog boxes that step through the process of adding a new address book.

If &Balsa; was not compiled with LDAP support it will not let you choose LDAP as an addressbook type. Once the type of address book is selected you must specify the name and location of the address book.

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

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.

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 mailbox as default. Use this page to set the &Balsa;'s behaviour regarding incoming and outgoing messages. 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. 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. Wrap Outgoing Text Have &Balsa; wrap all outgoing mail at the specified column. Forward button attaches mail 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 queues outgoing mail in outbox instead of sending it This option gives you control over when Balsa connects to a server to send messages. Encoding Set the character encoding method to either 7 bit, 8 bit, or what the quoted message is using. Reply prefix The string that Balsa should use as a prefix when quoting a message. Note: if you select `Send message as type text/plain; 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. Copy outgoing messages to sentbox Have Balsa save a copy of each message you send in the mailbox marked as the `Sentbox'. This page controls how &Balsa; appears to you. 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. Toolbars Use this to determine whether &Balsa;'s toolbars display only text, only icons, or both text and icons. 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. 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. Displayed Headers A space-separated list of the headers to display in the message window. &Balsa; uses five different levels of messages to inform you; use the options on this page to choose whether, and how, each level is shown. &Balsa; uses color to visually highlight various parts of the display; use the widgets on this page to control them. Fonts Use these controls to select the fonts to be used for the message body and the 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 colours 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. Wrap Incoming Text If selected, Balsa will wrap text of incoming messages at the specified line length. Prefer text/plain over html Messages that contain alternative text/plain and html versions of the content are often structured so that the html version is preferred. You can override that preference here. National (8-bit) characters You may receive messages that incorrectly contain national characters with no indication of how they are encoded. You can choose to have &Balsa; display them as "?" or to attempt to display them using a codeset from the drop-down list. &Balsa; can show the messages in a mailbox as a flat list, or threaded according to different algorithms. Expand mailbox tree on open This option controls whether threads are expanded or collapsed when the mailbox is first opened. Default threading style The threading style to be used for a mailbox is part of the mailbox properties. This option specifies the style to be used for a new mailbox. The pane to setup Balsa spell check options. Balsa uses the Portable Spell Checking library (pspell) to do 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 occaisonally 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 thourough 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. 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. 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. IMAP Folder Scan Depth Opening an &IMAP; folder 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. 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. You control whether and where the labels are shown using the popup (right click) menu for any actual toolbar, not this dialog. This is an instant apply dialog: the changes you make take effect immediately, as shown in the Preview toolbar; actual toolbars are updated when you close the dialog. Immediately 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. The folder configuration edit dialog allows you to configure entire mailbox sets on remote IMAP servers. Note that this IMAP folder support is still experimental and you may experience some difficulties if you have bad luck. 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. Port is the port number to be used for the connection. The default value is 143 but you may want to modify it if you use connection forwarding or your IMAP server runs on a nonstandard port number. User name is the name used for authorization on the IMAP server. 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". 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. This is to be filled in. You can choose among several address book types. 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. 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, 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 seperated 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 from the tab(\t), since that is the field seperator. 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! 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 This is to be filled in. This dialog window lets you specify how you present yourself to the rest of the world through your email. Your Name This doesn't have to be your name, I guess. But it's the word prefixing your email address in mail you send. E-Mail 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. Use Signature File When Sending Mail Include the signature file when sending email. Replying to Mail Include the signature file when replying to mail. Forwarding Mail Include the signature file when forwarding mail. Signature file The text to append to all your messages. This text can come from one of three places: 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 You also get to control when the signature is appended. Reply Prefix The character sequence to prefix quoted lines in a reply with. Enable Signature Separator When checked, this has &Balsa; insert the standard signature separator before your signature. 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 pages 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, it is 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. Each filter is made of one or several conditions, each one 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. Edition or creation of a condition is done in the condition window , that 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. 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. 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 does 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, 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" let 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. 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 reminded 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 : eg if a green 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 green 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 implented. 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 : it moves the selected filters from the left list to the right one, adding one more filter 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 two buttons under the right list serves 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. There are three buttons between the filters lists : The Apply button : this applies all filters of the right list to the entire mailbox immediately (be patient, this can take a quite long time on big mailboxes or remote ones). 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. 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 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 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. 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. 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! Balsa can expand the names of your contacts it finds in Balsa addressbooks. It will do this by both the Card Name (unique alias) and the Full Name. 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 fill in the best match. This is best demonstrated with the following picture:

The example shows what it looks like if Balsa Mailing List is in your address book, and you have typed "ba" If the match shown is what you want, simply press Enter to move to the next entry, or press Comma or End to type another e-mail address. If the match shown is not the one you want, pressing Tab will cycle through all possible matches. If there is only one match, it will move to the end of the match. At any point, you can simply continue typing and ignore the matched entry. To move to the next entry without accepting the shown entry, press the Down arrow. 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, under the Address Books tab. Also, some address books are expensive to lookup. You will need then to press Ctrl-R to explicitly expand the alias. 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 apriopriate 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 apropriate 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. 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! I thought I deleted that message! What's that window that flashed on the screen? The address book doesn't import my addresses. See this section. 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. There are some problems with libmutt and deleting messages. We believe them to be solved now, but they may be lingering. Known causes of messages seeming to be deleted but not really are: Mail arrives in the folder before the deletion is committed. This is believed to be solved. Many messages were deleted and the folder was closed and reopened quickly. This is also believed to be solved. 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. 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. &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) To find more information about it, please visit the &Balsa; Web page. 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 http://www.balsa.net/bugs.html. If you are using GNOME 1.1 or later, you can also use command bug-buddy for submitting bug reports. Following people contributed to this manual: Peter Bloomfield (@MindSpring.com) Matthew Guenther (guentherm@asme.org) 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 docs@gnome.org and the Balsa Discussion List balsa-list@gnome.org. You can also add your comments online by using GNOME Documentation Status Table. 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. Druid The GNOME equivalent to Microsoft Windows Wizards, a step by step dialog to guide the user through a setup procedure. 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 used by &Balsa; to handle local mail. 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 recieved 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 specifing 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 excatly 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 the upcoming Evolution. Many other programs are capable of exporting their contact lists in VCARD format as well.