## Balsa User's Guide

2000
Stuart Parameter
2000
Jay Painter
Peter
Williams

              peter@newton.cx

Matthew
Guenther

    	  mguenther@netcom.ca

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 1.1 of the Balsa manual.
20 May 2000

Balsa is a graphical mail client. While it is still 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 email 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 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 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.

## Getting Started with Balsa

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.

## The Main Window

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

### Menu & Toolbar

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

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

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

  - Ctrl-I File Print — Print the current message.

  - Ctrl-Q File Exit — Exit the program.

Message

  This menu has commands for manipulating messages.

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

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

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

  - M Message New — Send a new message.

  - R Message Reply — Reply to the current message.

  - A Message Reply to All

  - F Message Forward — Forward the currently selected message.

  - C Message Continue — Continue a postponed menu.

  - D Message Delete — Delete the currently selected message(s).

  - U Message Undelete — Undelete the currently selected message.

  - Message Wrap — If set, the message will be displayed with word wrap.

  - Message Show No Headers ,

    Show Selected Headers ,

    Show All Headers

    — Select the headers to display in the message. pane.

Mailbox

  For manipulating mailboxes.

  - Mailbox Add — Create a new mailbox.

  - Mailbox Edit — Edit mailbox properties.

  - Mailbox Delete — Delete a mailbox.

  - Mailbox Commit Current — Synchronize changes between the currently selected mailbox and the file on disk.

  - Mailbox Close — Close the currently selected mailbox.

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

Settings

  - Settings Preferences... — Open the Preferences Dialog.

  - Settings Show mailbox tree — Toggle the display of the mailbox tree in the main window.

  - Settings Show mailbox tabs — Toggle the display of tabs for all open mailboxes.

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

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

There are some useful hot-keys for the message index.

n

  Go to the next message

p

  Go to the previous message

d

  Delete the current message

u

  Undelete the current message

r

  Reply to the current message

a

  Reply-to-all the current message

f

  Forward the current message

There are also pop up menu items for many of the same functions.

New

  Compose a new message.

Reply

  Replies to the currently selected message(s).

Reply to All

  Replies-to-all the currently selected message(s).

Forward

  Forwards the currently selected message(s).

Delete

  Deletes the currently message(s).

Undelete

  Undeletes the currently selected message(s).

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

The message view displays the message that is selected in message list. It will attempt to display images in the message. Balsa does not understand HTML. (Someday, maybe.) Attachments will be shown as blue links that look like "--APPLICATION--". Clicking on the link will let you save (but not view) it. Right-click on a body of text to save it.

You are not restricted to that pane. Double-click on a message in the message index to open it in a separate window.

Balsa's message view is a little deficient. It will not allow the message text to be selected, and cannot handle MIME data other than images. Hopefully this will be fixed one day.

## The Message Composer

### Message Composition Window

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. In the near future, it will also be possible to spell check the message, as well as 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:

### 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... &mdash 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. (Using the method specified in the Preferences 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 using the command specified in the Preferences window.

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

  - 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 the lines in the paragraph the cursor is in 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.

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.

ISO Charset

  This menu provides a number of available character sets to use when composing and sending the message. Currently Balsa does not support multiple character sets in a single message.

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

Balsa Message Composer Toolbar

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.

Spelling

  Run the message through a spell-checker, not implemented in the current version (0.8.0)

Print

  Print out the draft of the message, using the print command specified in the Preferences dialog.

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 Preferences 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 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, the composition window supports drag-and-drop of addresses from the GnomeCard application.

### Attachments

#### List of Attachments

List of Attachments

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.

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

## The Preferences Window

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.

### Identity

This page lets you specify how you present yourself to the rest of the world.

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

  #### Signature

  Use this page to set up signature files and how Balsa will use them in your messages

  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 file to append to all your messages. 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.

  #### Mail Servers

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

  Remote Mailbox Servers

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

  Local Mail Directory

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

  Remote SMTP Server

    If your computer is not equipped with sendmail or you do not wish to use it, select this radio button and enter a host name to contact via SMTP.

  Local Mail User Agent

    Balsa will attempt to use sendmail to send mail. Unfortunately, you cannot specify the command to execute right now.

    ##### Mail Options

    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.

      Using "0" as an interval is a really bad idea.

    ###### Outgoing

    Wrap Outgoing Text

      Have Balsa wrap all outgoing mail at the specified column.

    Default Bcc

      An address to Blind Carbon Copy to on all emails.

    ##### Display

    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

      If Balsa was compiled with `--enable-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.

    ##### Printing

    Print Command

      The command executed when the print button is pressed. The message text in the command is signified by "%s".

    Break Line

      Whether to break the output line at a specified column, or to let the printing program do the wrapping to the page.

    ##### Encoding

    Set Balsa's character set encoding.

    Charset

      A string representing the character set for Balsa to use to use by default.

    Encoding

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

    ##### Misc

    Debug

      Set the display of debugging output to the console.

    Empty Trash on Exit

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

    Preview Pane Font

      The font used to display the text of the message in the preview pane.

    Unread Mailbox Colour

      Set the colour of mailboxes that contain unread messages.

    ##### Startup

    Check Mail at Startup

      If set, Balsa will automatically attempt to download mail from the POP3 mail server upon startup.

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

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

The mailbox may not appear in the list immediately, or in the current session of Balsa at all, but it exists. Yes, this is a bug. The best workaround is to make the mailboxes outside of Balsa, using `touch` or `maildirmake`

### Moving Messages

The easiest way to move messages around is to select them in the message index and use the Transfer context menu. It will let you choose a mailbox in the mailbox list and the messages will be moved there.

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

This can be done. It's ugly, but possible.

First, create the IMAP folder as you want it configured. It will appear as something like "INBOX on host.domain.org". Exit Balsa. (I told you this was bad.)

Open up ~/.balsarc in your favorite editor. There will be a visible organization to the file; find the place called "Accounts". There will be at least five definitions that look like "Inbox = {Type = local;Name = (etc.)". There will also be one that says something like "m1 = {Type = IMAP;Name = (etc.)". Edit the file to replace "m1" (or whatever number) with "Inbox", and it would be wise to change the "Name" field to "Inbox". Change the Inbox entry to be the opposite; Inbox becomes m1 and Name becomes Local Inbox (for example).

Close the .balsarc and restart Balsa. Your Inbox will now be an IMAP mailbox. Hopefully you can figure out how to make your other mailboxes IMAP-based from these instructions.

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

- It won't print!

- I thought I deleted that message!

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

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

### It won't print!

Your print command is probably wrong. It defaults to `"a2ps -d -q %s"`. Use the configuration window to change it to something that works.

### I thought I deleted that message!

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.

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

## Authours

Balsa was written by many people, including:

- Stuart Parameter (pavlov@pavlov.net)

- Jay Painter (jpaint@gimp.org)

- Peter Williams (peter@newton.cx)

- David Pickens (dpickens@iaesthetic.com)

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

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

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.

This manual was written by Peter Williams (peter@newton.cx) & Matthew Guenther (mguenther@netcom.ca).

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.

druid

  The GNOME equivalent to Microsoft Windows Wizards, a step by step dialog to guide the user through a setup procedure.

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.