X-New-Mail

Pop up a X notification window
when new mail arrives in MailDir

Copyright (C) 2004 DFG/M.Watermann, D-10247 Berlin, FRG
All rights reserved
EMail: Support@MWat.De

Table of Contents:

Overview  

This script is just a tiny utility used to show in a popup window a list of newly arrived emails, so you can eventually fire up your email program to read them and respond.

Presumed is a MailDir-style mail delivery, that is incoming mail is put in a directory with (possibly nested) subdirectories, each of which with cur/new/tmp subdirectories. Or, to put it the other way around: if you (i.e. your mail program) are using the mailbox-style storage for one reason or another you may skip this page (and program) and have a look at e.g. man xbiff.

Anyway, here we're only interested in the $MAILDIR/.../new/ directory where all incoming mail ends up (that is, until the users MUA moves it to the $MAILDIR/.../cur/ directory). This script doesn't care, how a email made its way into one of those ../new/ directories, e.g. by the PostFix MTA writing it directly, or by a MDA like procmail writing it after applying its receipts, or by other means. The only thing, actually, that counts in this context is the fact that there is a new file.

By comparing the filedate of the files inside the $MAILDIR hierachy (see the --maildir option below) with an internally maintained 0-byte flag file (~/.xnm.time) it's determined whether a file is considered new. Besides that before a files shows up in the notification window some more conditions must be met: it must be stored in a subdirectory named new as mentioned above and it must not be empty, i.e. contain the Date/From/Subject/To header fields which are to be shown by the notification window after a line stating the relative directory (i.e. w/o the $MAILDIR path) where the given mail was found (assuming you and your MUA are using meaningful directory names).

[up to Table of Contents]

Commandline Options

There are some optional commandline switches in both short and long variants which may be used. The long option names may be shortened to at least three letters; the phrase prints out means, the output is written to stdout (i.e. usually your display/screen) so that you can redirect it to a file or pipe through some other tool (e.g. lpr). – In alphabetical order:

-a or --all
While the script usually loops forever looking for new emails coming in, this switch causes it to terminate after showing all mail(s) not currently read (i.e. still in new directory, see above). In case there are no such mails, a short message indicating this fact is written to stdout.
-h or --help
Print out a short usage note and terminate without any further work. (See also the --html and --info options below.)
-H or --html
Print out this text in HTML format, suitable for reading with a HTML-viewer (aka web-browser), and terminate without any further work. (See also the --help and --info options.) [This switch produced what you're reading right now.]
-I or --info
Print out this text in ASCII format, suitable for printing, and terminate without any further work. (See also the --help and --html options above.)
-i secs or --interval secs
(Default: 120 secs) Number of seconds to sleep between each mail lookup. To follow the be-friendly-rule, after each directory scan the script goes sleeping for a while before starting a new scan. This option can be used to lengthen that time. – While it's possible as well to shorten the 2 minutes default to at least 1 second, there's no sense in doing so: apart from wasting system ressources for such a busy loop, most probably it would better to simply keep your MUA (email program) open if want some kind of, hmm, realtime access without running this script at all.
-k or --kill
This switch causes all instances of this script currently running to be terminated. – Please note, that a possibly active notification window is not affected by this switch so you'd have to close it manually if so you wished.
-m dir or --maildir dir
(Default: ~/Mail) The name of the directory tree to scan for new mails.
-n secs or --notify secs
(Default: 3600 secs) The number of seconds to show the notification window. The default value of one hour may seem very long. I've chosen it, because the window can be closed at any time anyway if you wish so. Additionally, I say, what's the purpose of a notification that just pops up and vanishes again after a short period while I happend to sit, er, recycling some biological stuff? Or distracted by a lenghty phone call demanding attention and support? Or breeding some cool ideas? Or ...
-t heading or --title heading
(Default: "new EMail") The window title of the notification window; the current date/time is automatically prepended.

[up to Table of Contents]

System tools used

The following utilities are used by this script and are assumed to be reachable in PATH (which is checked on startup, bailing out if one of this tools couldn't be found by the shell):

Xdialog
(see xdialog.dyns.net) creates the X window showing the arrived mails.
/bin/bash
is used to actually run this script i.e. trying to figure out what my code, er, is supposed to mean and interpret it for the underlaying GNU/Linux OS to let that one also know what to do, hmm, to satisfy my wishes ...
date
is used when this script is run for the very first time (or after deleting the ~/.xnm.time file, see the Files section below) to set (together with touch) the internal last checked flag, and it prepends the window title with the current time (as of showing that notification window).
killall
is used by the --kill switch (see above) to terminate any running instance of this script.
sed
extracts the email's header fields to be shown by the notification window, and it processes/creates the --html and --info output (see Commandline Options above).
sort
is asked to, well, sort the header fields shown by the notification window since there's no pre-defined order in an email head.
touch
is used when this script is run for the very first time (or after deleting the ~/.xnm.time file, see the Files section below) and with the --all switch (see above) to set (together with date) the internal last checked flag.

[up to Table of Contents]

Environment

There are no special requirements to run this script besides the availability of the system tools listed above. One (optional) environment variable may affect this script:

MAILDIR
If this variable is set (which is usually not the case unless you add an appropriate entry to your ~/.bash_profile shell configuration file) it's used as the default value for the mail directory to scan. Whether it's set or not, however, the --maildir commandline option (see above) will always override this setting. In other words: If you don't want to use the --maildir commandline option although your mail directory happens to be, say, ~/MailDir just add the line export MAILDIR=~/MailDir to your ~/.bash_profile and you're done (from the next time you log in, that is).

[up to Table of Contents]

Files

Apart from the system tools listed above the following files are used:

Xnm
This script you're just reading about. It may reside anywhere you wish, e.g. ~/bin would be fine or – if you happen to run the KDE desktop manager on top of X – the ~/.kde/Autostart directory might be handy.
~/.xnm.rc
In case you're familar with GTK this file may be used to customize the visual appearance of the notification window. Both the GTK name and class of the notification window are Xnm. – The script automatically creates a simple sample (sounds cool, doesn't it?) resulting in a lightyellow window background. If you prefer the Xdialog default (grayish) style, just delete this file (or trim it to 0 byte). – Any changes to this file come into effect the next time a notification window is created; there's no need to restart a running script instance.
~/.xnm.time
A 0-byte hidden dot-file used for time comparision. If you delete this file, all mails of the current day will be shown as new. – Please note, that you won't see any notification windows for, say, some time if you manage to change this file's time to some future date ...
~/.xnm.xpm
If you're not happy with (or just don't like) the icon I provided to be shown alongside the list of new emails, please feel free to copy any other XPM file that you find more fitting to this location. – In case you want to revert to the default one I created, just delete this file and the script will be happy to recreate the icon for you just before popping up another notification window.

[up to Table of Contents]

ChangeLog

    $Log: Xnm,v $
    Revision 1.5  2004/07/27 10:22:20  matthias
    * changed former --daily switch to --all, updated docs accordingly;
    
    Revision 1.4  2004/07/25 08:26:08  matthias
    + added -d|--daily option (replacing former --once switch);
    * modified sed script (for html output) to catch underlines at end'o'line;

    Revision 1.3  2004/07/21 10:19:18  matthias
    + added commandline handling (incl. some new options) to allow for
        changing the default values w/o editing the script;
    + added (lots of) documentation (available by --html and --info)
        and a brief usage text (-h or --help), the latter used by
        all startup error messages as well;
    * modified (simplyfied) file filtering in showWindow();
    * moved conditional icon creation from main() to showWindow() to allow
        for changing the icon at runtime w/o restart;

    Revision 1.2  2004/07/19 14:04:21  matthias
    + created an icon (~/.xnm.xpm) to be shown with the text;
    + added usage of a GTK+ configuration RC file (~/.xnm.rc);
    * instead of simply listing the filenames of new mail now the
        Date/From/Subject/To header fields of each mail are shown;
    * files ending with index/idx/sorted are excluded from processing;

[up to Table of Contents]