# &app; Manual V&manrevision;

## Introduction

&app; is a status icon (&aka; tray icon) that informs you if you have new mail.

It works with system trays implementing the freedesktop.org System Tray Specification, such as the GNOME Panel Notification Area, the Xfce Notification Area and the KDE System Tray.

&app; features include:

- multiple mailbox support

- &mbox;, &mh;, &maildir;, &pop3;, &imap;, &gmail;, Evolution and &sylpheed; support

- &sasl; authentication support

- APOP authentication support

- &ssl;/&tls; support

- automatic detection of mailbox format

- immediate notification (the status icon is updated immediately or within seconds after a mailbox changes)

- a mail summary

- HIG 2.0 compliance

## Getting Started

### To Start &app;

You can start &app; in the following ways:

Desktop menu

- Choose Preferences &app; (this location may vary across systems).

Command line

- To start &app; from a command line, type the following command, then press Return:

  `mail-notification` `options`

  where `options` is one or more options from the following non-exhaustive list:

  --version

- Show version information and compiled-in features

--enable-info

- Enable informational output

  #### Security

  The output of --enable-info may contain sensitive information such as passwords and session transcripts.

--display-properties

- Display the properties dialog

--display-about

- Display the about dialog

--close-popup

- Close the mail summary popup

--update

- Update the mail status

--unset-obsolete-configuration

- Unset obsolete GConf configuration

--quit

- Quit &app;

--help

- Show help

### When You Start &app;

When you start &app;, it stays in the background and monitors the status of your mailboxes.

When new mail arrives, an icon similar to the following one is displayed in the notification area (&aka; system tray):

#### &app; when there is new mail

Shows the &app; status icon.

Additionally:

- if a command to be executed when new mail arrives is set in the Commands properties, that command is executed

- if the Enable mail summary popup setting is enabled, an overview of new and unread messages is displayed

If an error is detected, the icon blinks (unless the Blink on errors setting is disabled).

Leaving your mouse over the icon will reveal more details about the status of your mailboxes. Clicking on the icon will perform the action specified in the Click Action setting.

## Properties

To configure &app;, choose Desktop Preferences Mail Notification (this location may vary across systems).

The Properties dialog contains the following tabbed sections:

- General

- Status Icon

- Mail Summary Popup

### General

General

- Display seen mail

- If this option is enabled, mail which is still marked as unread but has been seen will be displayed.

  The following mailbox types make a distinction between seen and unseen mail: &mbox;, &maildir;, &pop3;, &imap;, Evolution and &sylpheed;. Other mailbox types consider all unread mail as unseen.

Mailbox List

- This is the list of mailboxes to monitor for new mail. Selecting Add or Properties will display the Mailbox Properties dialog.

  You can drag a file or folder into this list.

  Small emblems may be displayed over mailbox icons. The following table summarizes them.

  ### Mailbox Emblems

  Icon | Signification
  Shows the emblem which is displayed when a mailbox has errors. | An error has occurred while trying to access the mailbox. The mailbox is unhandled.
  Shows the emblem which is displayed when a mailbox is checked periodically. | The mailbox does not support immediate notification, and is checked periodically according to its Delay between mail checks setting.
  Shows the emblem which is displayed when the format of a mailbox is unknown. | The format of the mailbox is unknown. The mailbox is unhandled.

Commands

- You can configure commands to be executed when new mail arrives and when all mail has been read.

### Status Icon

General

- Blink on errors

- If this option is enabled, &app; will show the status icon and make it blink on errors. Disabling this option is useful if some of your mailboxes are not permanently accessible.

Always display

- If this is option is enabled, &app; will display an icon even when there is no new mail.

Tooltip Mail Summary

- You can choose the layout of the tooltip mail summary (standard or compact), or you can choose to disable the tooltip mail summary (none).

Click Action

- You can choose an action to be performed when the mail icon is clicked: display this dialog, launch the mail reader or update the mail status.

### Mail Summary Popup

General

- Enable mail summary popup

- If this option is enabled, the mail summary popup will be displayed when new mail arrives.

Automatically close after

- If this option is enabled, the mail summary popup will be automatically closed after a delay has elapsed.

  The timer is restarted when new mail arrives.

Hide previously displayed mail

- If this option is enabled, the mail summary popup will only show new mail once (that is, the next time the mail summary is popped up, it will only display mail that was received since it was last popped up).

Position

- Position

- The location of the mail summary popup on the screen.

Horizontal offset

- The number of pixels to leave between the left or right side of the screen and the mail summary popup.

Vertical offset

- The number of pixels to leave between the top or bottom side of the screen and the mail summary popup.

Layout

- You can choose the layout of the mail summary: standard or compact.

Fonts

- You can choose to override your default theme fonts and use custom fonts in the mail summary popup. To further customise the appearance of &app;, see modifying-appearance.

  The specified fonts are relative to the text properties hard-coded into &app;, which cannot be modified: the title is printed in bold and uses a larger font size than the contents, and the message headers are printed in bold.

Display a Test Popup

- Clicking on this button will display an example popup, which can be used to ease configuration of the above options.

  Click on the example popup to close it.

## Mailbox Properties

The Mailbox Properties dialog is displayed when you add a new mailbox or when you edit an existing one. It contains the following global settings:

Mailbox type

- This is the type of the mailbox. If you select autodetect, the type will be autodetected using the mailbox &uri; and/or contents.

Mailbox name

- You can choose to assign a custom name to the mailbox. The mailbox name has informative purposes only, and is displayed in various parts of &app;. To reset to the default name, click on the Use Default button.

  The mailbox name will be modified automatically as you set some of the other options. To avoid losing your choice, only fill in the mailbox name after setting the other options.

Delay between mail checks

- This is the amount of time to wait between mail checks.

  This delay is only used if the mailbox does not support immediate notification of changes. If this is the case, an emblem will be displayed in the mailbox list.

The rest of the window depends on the selected mailbox type:

When autodetect is selected:

- Location

- This is the &uri; of the mailbox.

  &app; abstracts file operations by using &gnomevfs;. All the schemes (http, ftp, sftp, ...) supported by &gnomevfs; are therefore supported by &app;.

When POP3 or IMAP is selected:

- Hostname

- This is the hostname or IP address of the &pop3; or &imap; server.

  Symbolic names as well as IPv4 and IPv6 addresses are supported.

Username

- This is your username on the &pop3; or &imap; server. The username will be stored to disk unless it is left blank (in such case, a credentials prompt will appear when needed).

Password

- This is your password on the &pop3; or &imap; server. The password will be stored to disk unless it is left blank (in such case, a credentials prompt will appear when needed).

  ### Security

  To avoid sending your password over the network in clear text, you must either use a SSL/TLS connection or select a secure authentication mechanism. See below for more details.

Connection type and Port

- This is the type of connection to use and the port number to connect to.

  In-band SSL/TLS refers to a &ssl;/&tls; connection negotiated inside of the protocol (using the `STLS` &pop3; command or the `STARTTLS` &imap; command).

  SSL/TLS on separate port refers to the most widespread method for establishing a &ssl;/&tls; connection: using a separate port.

  The security considerations listed below do not apply if you select SSL/TLS (either in-band or on separate port).

Authentication mechanism

- This is the authentication mechanism to use. If you select autodetect, all the authentication mechanisms supported by the &pop3; or &imap; server will be tried, in descending order of security. Otherwise, the selected mechanism (and only the selected mechanism) will be used.

  ### Security

  If autodetect is selected and secure authentication fails, your credentials may be sent over the network in clear text (unless you use a &ssl;/&tls; connection).

  If this is a concern, select the appropriate secure authentication mechanism from the drop-down list.

When IMAP is selected:

- Mailbox

- This is the &imap; mailbox to use.

Use the IDLE extension

- The IDLE extension (as defined by RFC 2177) allows &app; to stay connected to the server and provide immediate notification of changes.

  If never is selected, &app; will never use the IDLE extension, not even if the server supports it. Use this option if it appears that &app; does not detect changes to an &imap; mailbox while the IDLE extension is in use. If using this option fixes the issue, please also send the &imap; session transcript (obtained by running &app; using the --enable-info option) to Jean-Yves Lefort jylefort@brutele.be.

  If autodetect is selected, &app; will use the IDLE extension if the server supports it, unless the server software is known to have a broken IDLE implementation (currently, the only such software known to &app; is the University of Washington imapd). This is the recommended choice.

  If always is selected, &app; will use the IDLE extension if the server supports it, regardless of the server software. Use this option if you want to force &app; to use the IDLE extension, even if it has detected a bogus implementation.

When Gmail is selected:

- Username

- This is your username on &gmail;. The username will be stored to disk unless it is left blank (in such case, a credentials prompt will appear when needed).

Password

- This is your password on &gmail;. The password will be stored to disk unless it is left blank (in such case, a credentials prompt will appear when needed).

When Evolution is selected:

- Folder

- This is the Evolution folder to monitor for changes.

  For the folder selector to be available and for monitoring an Evolution mailbox, Evolution must be running and the Evolution Mail Notification plugin must be loaded.

## Troubleshooting

If &app; does not work as expected, remember that you can obtain more details by leaving your mouse over its icon.

Additionally, a very efficient way to identify and solve problems is to run &app; using the --enable-info option and examine the output.

### Security

The output of --enable-info may contain sensitive information such as passwords and session transcripts.

## Technical Information

### Immediate Notification

Immediate notification is the ability to detect changes to a mailbox without needing to check it periodically. It allows the status icon to be updated immediately (or within seconds) after a mailbox changes.

Requirements for immediate notification to be enabled:

&mbox;, &mh;, &maildir; and &sylpheed; mailboxes:

- &gnomevfs; must be compiled with FAM support, and FAM must be configured properly.

  Refer to the

  fam

  1 manual page for more details.

&imap; mailboxes:

- The &imap; server must support the IDLE extension, as defined by RFC 2177.

Evolution mailboxes:

- There is no requirement. Immediate notification is always enabled.

&pop3; and &gmail; mailboxes:

- Immediate notification is not supported by these mailbox types.

If immediate notification cannot be enabled for a mailbox (either because that type of mailbox does not support it or because the requirements are not met), the mailbox will be checked periodically according to its Delay between mail checks setting, and an emblem will be displayed in the mailbox list.

### POP3 Implementation

The &app; &pop3; implementation strictly conforms to RFC 1939, RFC 2449, RFC 1734, RFC 2595 and RFC 2384.

The AUTH, APOP and USER/PASS authentication mechanisms are supported, and the LOGIN-DELAY capability is honoured. The TOP optional command is supported.

The authentication logic can be represented with the following pseudo-code:

    success = false;

    if (mailbox.config.authmech != autodetect) {
      if (mailbox.config.authmech in server.supported_authmechs) {
        success = server.authenticate(mailbox.config.authmech);
      }
    } else {
      if (has_sasl_support && server.supports_sasl) {
        foreach authmech in server.supported_authmechs {
          if (server.ssl_connection || ! authmech.plaintext) {
            success = server.authenticate(authmech);
            if (success)
              break;
          }
        }
        if (! success && server.supports_apop) {
          success = server.authenticate(apop);
        }
        if (! success) {
          success = server.authenticate(userpass);
        }
      }
    }

    if (! success) {
      mailbox.error = "authentication failed";
    }

### IMAP Implementation

The &app; &imap; implementation strictly conforms to RFC 3501, RFC 2177 and RFC 2192.

The AUTHENTICATE and LOGIN authentication mechanisms are supported, and the IDLE extension is implemented.

The authentication logic can be represented with the following pseudo-code:

    success = false;

    if (mailbox.config.authmech != autodetect) {
      if (mailbox.config.authmech in server.supported_authmechs) {
        success = server.authenticate(mailbox.config.authmech);
      }
    } else {
      if (has_sasl_support && server.supports_sasl) {
        foreach authmech in server.supported_authmechs {
          if (server.ssl_connection || ! authmech.plaintext) {
            success = server.authenticate(authmech);
            if (success)
              break;
          }
        }
        if (! success && server.supports_login) {
          server.authenticate(login);
        }
      }
    }

    if (! success) {
      mailbox.error = "authentication failed";
    }

### Modifying the Appearance of &app;

&app; sets names for several widgets and icons, so that they can easily be matched in a GTK+ resource file.

### Widget Names

Widget | Name
mail summary popup | mn-mail-summary-popup
mail summary popup title | mn-mail-summary-popup-title
message list | mn-message-view
tooltip section title | mn-tooltip-section-title
tooltip section body (except message list) | mn-tooltip-section-body

### Icon Names

Icon | Name
status icon when there is new mail | mn-mail
status icon when there is no new mail | mn-no-mail
local mailbox | mn-local
remote mailbox | mn-remote
polled mailbox | mn-polled
unknown mailbox format | mn-unknown
mailbox error | mn-error
Gmail mailbox | mn-gmail
system mailbox | mn-system-mailbox
Evolution mailbox | mn-evolution-mailbox
select all | mn-select-all
mail summary | mn-mail-summary
mail reader | mn-mail-reader
connect (in the SSL/TLS confirmation dialog) | mn-connect

More information about GTK+ resource files, including a description of their format, can be found in the Resource Files section of the GTK+ Reference Manual.

#### Examples

You can modify the appearance of &app; by editing the `~/.gtkrc-2.0` file.

To use a large font for the mail summary popup title:

    style "mn-mail-summary-popup-title"
    {
      font_name = "Sans 14"
    }

    widget "*.mn-mail-summary-popup-title"
      style "mn-mail-summary-popup-title"

To use a small font for the mail summary popup messages:

    style "mn-mail-summary-popup-messages"
    {
      font_name = "Sans 8"
    }

    widget "mn-mail-summary-popup.*.mn-message-view"
      style "mn-mail-summary-popup-messages"

To use a small font for the mail summary tooltip messages:

    style "mn-mail-summary-tooltip-messages"
    {
      font_name = "Sans 8"
    }

    widget "gtk-tooltips.*.mn-message-view"
      style "mn-mail-summary-tooltip-messages"

To use some custom icons:

    pixmap_path "/home/myaccount/icons"

    style "mn-icons"
    {
      stock["mn-local"] =
      {
        { "local.png" }
      }
      stock["mn-remote"] =
      {
        { "remote.png" }
      }
    }

    widget "*" style "mn-icons"

## Frequently Asked Questions

How can I access the Properties dialog?

Choose Desktop Preferences Mail Notification (this location may vary across systems) or type `mail-notification -p` in a terminal.

You say that &app; supports <insert mailbox type or feature>, but there is no such entry in the Mailbox Properties dialog.

&app; was built without support for <insert mailbox type or feature>.

If you have installed &app; from a package, contact the package maintainer and ask him to enable <insert mailbox type or feature> support.

If you have built &app; yourself, install the <insert mailbox type or feature> prerequisites (they are listed in the `INSTALL` file), then rebuild &app;.

I need &ssl;/&tls; for connecting to my &pop3; or &imap; server, but the &ssl;/&tls; options are greyed out.

See the previous question.

How can I monitor multiple &imap; folders?

Add each folder as a separate &app; mailbox.

Can I monitor a <insert webmail provider> account?

&app; has no native support for <insert webmail provider> mailboxes. However, &app; supports the &pop3; and &imap; protocols; you can therefore use a separate application for providing &pop3; or &imap; access to the <insert webmail provider> account.

## About &app;

&app; was written by Jean-Yves Lefort jylefort@brutele.be. To find more information about &app;, visit the Mail Notification web page.

### Reporting Bugs and Other Feedback

Bug reports and feedback should be sent to Jean-Yves Lefort jylefort@brutele.be.

### Acknowledgements

- Claudio André

- Hendrik Brandt

- Kim Briggs

- Hiroshi Hasebe

- Duarte Henriques

- Dan Korostelev

- Pav Lucistnik

- Filip Miletic

- Phil Nelson

- Daniel Nylander

- Maurycy Pawłowski-Wieroński

- Vladimir Petkov

- Benoît Rouits

- Tomasz Sarota-Raczek

- Edwin Shin

- Marcel J. Zwiebel

### Licensing Terms

&software-license;

## Glossary

## G

Gmail

A free webmail service operated by Google. More information can be found on the Gmail web page.

GnomeVFS

A filesystem abstraction library allowing applications to access local, remote and virtual resources in a transparent fashion. GnomeVFS is part of the GNOME Desktop Environment.

## I

IMAP
Internet Message Access Protocol IMAP

A protocol allowing a client to access and manipulate electronic mail messages on a server. &app; implements version 4rev1 of the protocol, as defined by RFC 3501.

## M

Maildir

A mailbox format popularised by the qmail mail transfer agent. Messages are stored in a structure of directories for reliability.

mbox

The traditional UNIX mailbox format. Messages are stored in a single file.

MH

A mailbox format popularised by the MH mail user agent. Messages are stored as separate files for flexibility and performance.

## P

POP3
Post Office Protocol Version 3 POP3

A protocol allowing a workstation to dynamically access a maildrop on a server host, as defined by RFC 1939.

## S

SASL
Secure Sockets Layer SSL

A protocol securing a connection through the use of cryptographic techniques.

Simple Authentication and Security Layer SASL

A method for adding authentication support to connection-based protocols, as defined by RFC 2222.

SSL
Sylpheed

The mailbox format used by the Sylpheed mail user agent. The Sylpheed format adds a binary cache to MH folders for faster indexing.

## T

TLS
Transport Layer Security TLS

A protocol securing a connection through the use of cryptographic techniques, as defined by RFC 2246. TLS is the successor of &ssl;.

## U

Uniform Resource Identifier URI

A compact string of characters for identifying an abstract or physical resource, as defined by RFC 2396.

URI