# &app; Manual V&manrevision;

2004 Jean-Yves Lefort
&project; &documentation-license;
Jean-Yves Lefort
&project;

    jylefort@brutele.be

Mail Notification Manual V&manrevision;
&date;

Jean-Yves Lefort jylefort@brutele.be

&project;

Mail Notification Manual V2.9
Monday, November 15, 2004

Jean-Yves Lefort jylefort@brutele.be

&project;

Mail Notification Manual V2.8
Thursday, November 4, 2004

Jean-Yves Lefort jylefort@brutele.be

&project;

Mail Notification Manual V2.7
Sunday, October 31, 2004

Jean-Yves Lefort jylefort@brutele.be

&project;

Mail Notification Manual V2.6
Monday, October 25, 2004

Jean-Yves Lefort jylefort@brutele.be

&project;

Mail Notification Manual V2.5
Wednesday, October 6, 2004

Jean-Yves Lefort jylefort@brutele.be

&project;

Mail Notification Manual V2.4
Thursday, September 9, 2004

Jean-Yves Lefort jylefort@brutele.be

&project;

Mail Notification Manual V2.3
Thursday, August 19, 2004

Jean-Yves Lefort jylefort@brutele.be

&project;

Mail Notification Manual V2.2
Monday, August 16, 2004

Jean-Yves Lefort jylefort@brutele.be

&project;

Mail Notification Manual V2.1
Wednesday, July 21, 2004

Jean-Yves Lefort jylefort@brutele.be

&project;

Mail Notification Manual V2.0
Tuesday, June 29, 2004

Jean-Yves Lefort jylefort@brutele.be

&project;

This manual describes version &appversion; of Mail Notification.

Feedback

To report a bug or make a suggestion regarding the &app; application or this manual, follow the directions in .

## 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;, &sylpheed;, &pop3;, &imap; and &gmail; support

- &sasl; authentication support

- APOP authentication support

- &ssl;/&tls; support

- automatic detection of mailbox format

- immediate notification (the status icon is updated 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:

Applications menu

  Choose Internet &app; .

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:

  --enable-info

    Enable informational output

    Security

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

  --list-features

    List compiled-in features and exit

  --display-mail-summary

    Display the mail summary dialog

  --display-properties

    Display the properties dialog

  --display-about

    Display the about dialog

  --close-popup

    Close the mail summary popup

  --update

    Update the mail status

  --report

    Report the mail status

    Security

    The output of --report may contain mailbox passwords.

  --unset-obsolete-configuration

    Unset obsolete GConf configuration and exit

  --help

    Show help and exit

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

- the Mail Notification > New Mail GNOME sound event is emitted (you can configure the sound to be played from the GNOME sound preferences)

- 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. Double-clicking on the icon will perform the action specified in the Double-click Action setting.

## Properties

To configure &app;, choose Applications Desktop Preferences Mail Notification (or on some systems Applications Preferences More Preferences Mail Notification ).

The Properties dialog contains the following tabbed sections:

- General

- Mailboxes

- Mail Summary Popup

### General

General
  Start Mail Notification on GNOME login

    If this option is enabled, &app; will be started along with your GNOME session.

  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.

  Display mail summary in tooltip

    If this option is enabled, the mail summary will be displayed in the status icon tooltip.

Commands

  You can specify a mail reader (which can be launched from various parts of &app;), as well as configure commands to be executed when new mail arrives and when all mail is read.

Double-click Action

  You can choose an action to be performed when the mail icon is double-clicked: display the mail summary dialog or launch the mail reader. The latter is only available if a mail reader is configured in the Commands properties.

### Mailboxes

General
  Delay between mail checks

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

    This delay only applies to mailboxes which do not support immediate notification of changes.

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.

### Mail Summary Popup

General
  Enable mail summary popup

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

    The mail summary popup will not be displayed if the Mail Summary dialog is displayed.

  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.

  Only display recent mail

    If this option is enabled, the mail summary popup will hide previously displayed mail.

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.

Fonts

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

  Title font

    If this option is enabled, the title of the mail summary popup will use the specified font.

  Contents font

    If this option is enabled, the contents of the mail summary popup will use the specified font.

  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.

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

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.

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

  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 password 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 idle mode if possible

    If this option is enabled and the &imap; server supports the IDLE extension (as defined by RFC 2177), &app; will stay connected to the server and provide immediate notification of changes.

    Some &imap; server programs (most notably, Pine imapd) are known to have a broken implementation of the IDLE extension.

    If &app; does not detect changes to an &imap; mailbox, disabling this option might fix the problem.

When Gmail is selected:
  Username

    This is your username on &gmail;.

  Password

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

## Mail Summary

The Mail Summary dialog can be accessed by double-clicking on the mail icon, or by right-clicking on it and choosing Mail Summary.

The Mail Summary dialog displays the list of new and unread messages, sorted by sent date in descending order.

To be able to extract messages from mbox, MH, Maildir, POP3, IMAP and Sylpheed mailboxes, &app; must have been compiled with MIME support.

&app; has been compiled with MIME support if `mail-notification --list-features` lists the MIME feature.

## 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 poll it periodically. It allows the status icon to be updated 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.

&pop3; and &gmail; mailboxes:

  Immediate notification is not supported.

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 the Delay between mail checks setting.

### POP3 Implementation

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

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

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

    if has-user-selected-mechanism then
      if server-supports-user-selected-mechanism then
        attempt authentication using user-selected-mechanism
      endif
    else
      if has-sasl-support and server-supports-sasl then
        if is-ssl-connection then
          sasl-mechanism = any
        else
          sasl-mechanism = any-non-plaintext
        endif
        attempt authentication using sasl-mechanism
      endif
      if authentication-failed and server-supports-apop then
        attempt authentication using apop
      endif
      if authentication-failed then
        attempt authentication using user/pass
      endif
    endif

### IMAP Implementation

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

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:

    if has-user-selected-mechanism then
      if server-supports-user-selected-mechanism then
        attempt authentication using user-selected-mechanism
      endif
    else
      if has-sasl-support and server-supports-sasl then
        if is-ssl-connection then
          sasl-mechanism = any
        else
          sasl-mechanism = any-non-plaintext
        endif
        attempt authentication using sasl-mechanism
      endif
      if authentication-failed and server-supports-login then
        attempt authentication using login
      endif
    endif

### 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 box | mn-message-box
message header name | name
message header value | value
tooltip section title | mn-tooltip-section-title
tooltip section body | mn-tooltip-section-body

Icon Names

Icon | Name
--- | ---
status icon | mn-mail
local mailbox | mn-local
remote mailbox | mn-remote
unsupported mailbox | mn-unsupported
Gmail mailbox | mn-gmail
system mailbox | mn-system-mailbox
select all | mn-select-all
mail summary | mn-mail-summary

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-box.*"
      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-box.*"
      style "mn-mail-summary-tooltip-messages"

To use italic for the message header names:

    style "mn-message-header-name"
    {
      font_name = "Italic"
    }

    widget "*.mn-message-box.*.name"
      style "mn-message-header-name"

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"

## About &app;

&app; was written by Jean-Yves Lefort (jylefort@brutele.be). To find more information about &app;, please 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

- Hendrik Brandt

- Duarte Henriques

- Dan Korostelev

- Filip Miletic

- Phil Nelson

- Vladimir Petkov

- Tomasz Sarota-Raczek

- Edwin Shin

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