# &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;, &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 the compiled-in features

--display-main-window

- Display the main window

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

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

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

## Main Window

You can access the main window in the following ways:

Applications menu

- Choose Internet &app; .

Command line

- Type the following command, then press Return:

  `mail-notification --display-main-window`

Mail icon

- Right-click on the mail icon and choose Main Window.

The main window displays the list of new and unread messages, sorted by sent date in descending order.

The main window can also be used to invoke &app; features when the mail icon is hidden.

### Editing the Main Window Toolbars

To edit the main window toolbars, choose Edit Toolbars , then:

- To add or remove buttons from your toolbars, drag icons from and to the editor.

- To reset the toolbars configuration to factory defaults, click on the Use Default button.

- To add a new toolbar, click on the Add a New Toolbar button.

- To remove a toolbar, remove all items from it. The toolbar will then automatically be removed.

- Drag buttons to rearrange them either on the same toolbar or between different toolbars.

## 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 main window, launch the mail reader or update the mail status.

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

  If all the mailboxes support immediate notification, this control is disabled.

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

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

## 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 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 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 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 | 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
mail reader | mn-mail-reader
main window | mn-main-window
leave fullscreen | mn-leave-fullscreen

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"

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

- Hendrik Brandt

- Duarte Henriques

- Dan Korostelev

- Filip Miletic

- Phil Nelson

- Maurycy Pawłowski-Wieroński

- 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