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

- Evolution, Gmail, &imap;, &maildir;, &mbox;, &mh;, &mozilla; products (Mozilla, SeaMonkey, Thunderbird, …), &pop3;, &sylpheed;, Windows Live Hotmail and Yahoo! Mail 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)

- message popups

- HIG 2.0 compliance

## Getting Started

### To Start &app;

You can start &app; in the following ways:

System menu

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

Command line

- To start &app; from a command line, type the following command in a terminal:

  `mail-notification` `options`

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

  -v, --version

- Show version information and compiled-in features

-i, --enable-info

- Enable informational output

  #### Security

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

-p, --display-properties

- Display the properties dialog

-a, --display-about

- Display the about dialog

-r, --consider-new-mail-as-read

- Consider new mail as read

-u, --update

- Update the mail status

-s, --print-summary

- Print a XML mail summary

--unset-obsolete-configuration

- Unset obsolete GConf configuration

-q, --quit

- Quit &app;

-?, --help

- Show help

### When You Start &app;

When you start &app;, it puts itself 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). The number of new messages is displayed over the icon.

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

Shows the &app; status icon.

Additionally:

- if the Play a sound when new mail arrives setting is enabled, that sound is played

- if the Enable message popups setting is enabled, information about each new message is popped up on your desktop

If an error is detected, the icon blinks.

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 System Preferences Mail Notification (this location may vary across systems).

The Properties dialog contains the following tabbed sections:

- General

- Status Icon

- Message Popups

In addition, at the bottom of the dialog, the Display test messages setting can be used to test the various settings against test messages.

### General

General

- Play a sound when new mail arrives

- If this setting is enabled, the selected sound will be played when new mail arrives.

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.

### Status Icon

Click Action

- Launch the mail reader

- Launches the GNOME mail reader. To specify your preferred mail reader, choose System Preferences Preferred Applications (this location may vary across systems).

Open the latest message

- Opens the most recent message, if supported.

  This is equivalent to clicking on the Open button in the message popup. See the Message Actions section for more details.

Consider new mail as read

- Hides the messages received so far. This action has no permanent effects: your mailboxes will not be modified, and the messages will no longer be hidden the next time &app; is started.

Update the mail status

- Checks for new mail in all mailboxes which do not support immediate notification.

### Message Popups

General

- Enable message popups

- If this setting is enabled, an information window will be popped up on your desktop whenever a new message arrives.

Position

- The location of the message popups on the screen.

  Attached to the status icon

- Message popups will be placed next to the status icon.

In the popup stack

- Message popups will be stacked together in one corner of your screen.

Expiration

- You can choose to have message popups stay on the screen until you click on them, or have them disappear after a delay has elapsed.

## Mailbox Properties

The Mailbox Properties dialog is displayed when you add a new mailbox or when you edit an existing one. It may contain the following tabbed sections:

- General

- Connection

- Details

### General

General

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

Location (Autodetect and System mailbox only)

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

Account (Gmail, IMAP, POP3, Windows Live Hotmail and Yahoo! Mail only)

- Server (IMAP and POP3 only)

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

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

Username

- This is your username on the mail server.

Password

- This is your password on the mail server. If the password is filled in, it will be stored in your default keyring. If it is left out, a password prompt will appear when needed.

  #### IMAP and POP3 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 the Authentication Mechanism setting for more details.

IMAP Mailbox (IMAP only)

- This is the &imap; mailbox to use.

Folder (Evolution only)

- 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 Jean-Yves Lefort's Mail Notification plugin must be loaded.

### Connection (IMAP and POP3 only)

Connection type

- 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 `STARTTLS` &imap; command or the `STLS` &pop3; command).

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

Authentication

- Mechanism

- This is the authentication mechanism to use. If you select autodetect, all the authentication mechanisms supported by the &imap; or &pop3; 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.

Use the IDLE extension (IMAP only)

- 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 setting if it appears that &app; does not detect changes to an &imap; mailbox while the IDLE extension is in use. If using this setting 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 setting if you want to force &app; to use the IDLE extension, even if it has detected a bogus implementation.

### Details

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

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.

## Advanced Configuration

### Message Actions

Message popups support the following actions:

- Open

- Mark as Read

- Mark as Spam

- Delete

Note that the Delete action is disabled by default. It can be enabled by modifying the /apps/mail-notification/popups/actions GConf key. See the GConf Settings section for more details about the GConf database.

#### Built-in Actions

The following table summarizes the currently implemented built-in actions for each mailbox type.

#### Built-in Actions

Mailbox Type | Open | Mark as Read | Mark as Spam | Delete
Evolution | yes | yes | yes | yes
Gmail | yes | no | no | no
&imap; | no | no | no | no
&maildir; | yes | yes | no | yes
&mbox; | no | no | no | no
&mh; | yes | no | no | no
&mozilla; | no | no | no | no
&sylpheed; | yes | yes | no | no
&pop3; | no | no | no | no
Windows Live Hotmail | no | no | no | no
Yahoo! Mail | no | no | no | no

#### Custom Actions

To define a custom action for a particular mailbox, edit the `~/.gnome2/mail-notification/mailboxes.xml` file and specify a command to be executed when the action button is clicked.

If both a built-in action and a custom action exists, the custom action overrides the built-in action.

XML attributes should be added to the `mailbox` element of the mailbox you want the actions to be available for. The following table specifies which XML attribute should be used for a particular action.

#### Action Attributes

Action | XML Attribute
Open | `open-command`
Mark as Read | `mark-as-read-command`
Mark as Spam | `mark-as-spam-command`
Delete | `delete-command`

Before executing a command, some strings will be substituted. The following table summarizes the available substitutions.

#### Command String Substitutions

String | Substitution
`%%` | a single percent character
`%sent-time` | the message timestamp expressed in seconds since the Epoch (00:00:00 UTC, January 1, 1970)
`%id` | the message unique identifier
`%from` | the message sender
`%subject` | the message subject, if any
`%uri` | the message &uri;, if any
`%filename` | if the message has an &uri; and that &uri; points to a local filename, that filename
`%uid` | the Evolution message UID, if any

- Substitutions will be shell-quoted as appropriate, you therefore must not quote the percent strings.

- Keywords can be enclosed in braces, as in `%{from}`.

Example:

    <?xml version="1.0"?>
    <mailboxes>
      <mailbox
        type="custom-vfs"
        uri="file:///home/jylefort/Mail/misc"
        open-command="my-open-script %filename"
        mark-as-spam-command="my-spam-script %filename"/>
    </mailboxes>

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

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.

### Widget Names

Widget | Name
mail icon and message count | mn-mail-icon
tooltip section title | mn-tooltip-section-title
tooltip section body (except mail summary) | mn-tooltip-section-body
tooltip mail summary | mn-message-view

### 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
autodetect (in the Mailbox type drop-down menu) | mn-unknown
mailbox error | mn-error
Gmail mailbox | mn-gmail
Yahoo! Mail mailbox | mn-yahoo
Windows Live Hotmail mailbox | mn-hotmail
system mailbox | mn-system-mailbox
Evolution mailbox | mn-evolution-mailbox
mail reader | mn-mail-reader
open message | mn-open-message
consider new mail as read | mn-consider-new-mail-as-read

#### Examples

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

To use a larger font for the message count of the mail icon, and display it on a yellow background:

    style "mn-mail-icon"
    {
      font_name = "Sans 12"
      bg[NORMAL] = "#FFFF00"
    }

    widget "*.mn-mail-icon" style "mn-mail-icon"

To use a smaller 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-mail"] =
      {
        { "my-mail-icon.png" }
      }
      stock["mn-no-mail"] =
      {
        { "my-no-mail-icon.png" }
      }
    }

    widget "*" style "mn-icons"

### GConf Settings

A number of advanced settings are available in the /apps/mail-notification namespace of the GConf database. To modify these settings, type the following command in a terminal:

`gconf-editor /apps/mail-notification`

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

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

- &gnomevfs; must support monitoring (it usually does).

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

Gmail, &pop3;, Windows Live Hotmail and Yahoo! Mail 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.

### 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";
    }

## Frequently Asked Questions

How can I access the Properties dialog?

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

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

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

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

If you have built &app; yourself, install the <mailbox type> 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; settings are greyed out.

&app; was built without &ssl;/&tls; support.

If you have installed &app; from a package, contact the package maintainer and ask him to enable &ssl;/&tls; support.

If you have built &app; yourself, install the &ssl;/&tls; prerequisites (they are listed in the `INSTALL` file), then rebuild &app;.

When monitoring a &pop3; mailbox, &app; reports all messages as new.

This is caused by limitations in the &pop3; protocol. You should configure your mail reader so that it deletes mail from the server after downloading it.

How can I monitor multiple &imap; folders?

Add each folder as a separate &app; mailbox.

Can I monitor a <webmail provider> account?

&app; has no native support for <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 <webmail provider> account.

How can I access message data from the new mail command?

Parse the output of `mail-notification --print-summary`.

I do not use &app; but I am presented with the properties dialog each time I log in. How can I disable it?

1. Choose System Preferences Sessions (this location may vary across systems).

2. Select the Startup Programs tab.

3. Uncheck the Mail Notification entry.

## About &app;

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

### Reporting Bugs and Other Feedback

Bug reports and feature requests should be filed in the Mail Notification bug tracker. Other feedback can be sent to Jean-Yves Lefort jylefort@brutele.be.

### Acknowledgements

- Claudio André

- Hendrik Brandt

- Kim Briggs

- Hiroshi Hasebe

- Duarte Henriques

- Nacho Hermoso de Mendoza

- Dan Korostelev

- Pav Lucistnik

- Filip Miletic

- Phil Nelson

- Daniel Nylander

- Lorenzo Orlandini

- Maurycy Pawłowski-Wieroński

- Vladimir Petkov

- Benoît Rouits

- Tomasz Sarota-Raczek

- Tomasz Sałaciński

- Edwin Shin

- Topi

- Marcel J. Zwiebel

### Licensing Terms

&software-license;

## Glossary

## G

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.

Mozilla

In this manual, a Mozilla mailbox refers to a mailbox produced by a Mozilla-based mail reader (Mozilla, SeaMonkey, Thunderbird, …). This mailbox format only differs from the &mbox; format by the fact that message status information is stored in the `X-Mozilla-Status` header instead of the `Status` header.

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