Ubuntu Manpage: mu_easy - a quick introduction to mu

Provided by: maildir-utils_1.2.0-2build1_amd64

NAME

       mu_easy - a quick introduction to mu

DESCRIPTION

       mu is a set of tools for dealing with e-mail messages in Maildirs. There are many options,
       which are all described in the man pages for the  various  sub-commands.  This  man  pages
       jumps  over  all  of  the  details and gives examples of some common use cases. If the use
       cases described here do not precisely do what you want, please check  the  more  extensive
       information  in  the  man page about the sub-command you are using -- for example, the mu-
       index(1) or mu-find(1) man pages.

       NOTE: the index command (and therefore, the ones that  depend  on  that,  such  as  find),
       require  that you store your mail in the Maildir-format. If you don't do so, you can still
       use the other commands, but you won't be able to index/search your mail.

       By default, mu uses colorized output when it thinks your terminal is capable of doing  so.
       If  you don't like color, you can use the --nocolor command-line option, or set either the
       MU_NOCOLOR or the NO_COLOR environment variable to non-empty.

INDEXING YOUR E-MAIL

       Before you can search e-mails, you'll first need to index them:

         $ mu index

       The process can take a few minutes, depending on the amount of mail you have, the speed of
       your  computer, hard drive etc. Usually, indexing should be able to reach a speed of a few
       hundred messages per second.

       mu index guesses the top-level Maildir to do its job; if it guesses wrongly, you  can  use
       the  --maildir option to specify the top-level directory that should be processed. See the
       mu-index(1) man page for more details.

       Normally, mu index visits all the directories under the top-level  Maildir;  however,  you
       can  exclude  certain  directories (say, the 'trash' or 'spam' folders) by creating a file
       called .noindex in the directory. When mu sees such a file, it will exclude this directory
       and its sub-directories from indexing.  Also see .noupdate in the mu-index(1) manpage.

SEARCHING YOUR E-MAIL

After you have indexed your mail, you can start searching it. By default, the search
results are printed on standard output. Alternatively, the output can take the form of
Maildir with symbolic links to the found messages. This enables integration with e-mail
clients; see the mu-find(1) man page for details, the syntax of the search parameters and
so on. Here, we just give some examples for common cases.

First, let's search for all messages sent to Julius (Caesar) regarding fruit:

$ mu find t:julius fruit

This should return something like:

2008-07-31T21:57:25 EEST John Milton <jm@example.com> Fere libenter homines id quod volunt credunt

This means there is a message to 'julius' with 'fruit' somewhere in the message. In this
case, it's a message from John Milton. Note that the date format depends on your the
language/locale you are using.

How do we know that the message was sent to Julius Caesar? Well, it's not visible from the
results above, because the default fields that are shown are date/sender/subject. However,
we can change this using the --fields parameter (see the mu-find(1) man page for the
details):

$ mu find --fields="t s" t:julius fruit

In other words, display the 'To:'-field (t) and the subject (s). This should return
something like:
Julius Caesar <jc@example.com> Fere libenter homines id quod volunt credunt

This is the same message found before, only with some different fields displayed.

By default, mu uses the logical AND for the search parameters -- that is, it displays
messages that match all the parameters. However, we can use logical OR as well:

$ mu find t:julius OR f:socrates

In other words, display messages that are either sent to Julius Caesar or are from
Socrates. This could return something like:

2008-07-31T21:57:25 EEST Socrates <soc@example.com> cool stuff
2008-07-31T21:57:25 EEST John Milton <jm@example.com> Fere libenter homines id quod volunt credunt

What if we want to see some of the body of the message? You can get a 'summary' of the
first lines of the message using the --summary-len option, which will 'summarize' the
first n lines of the message:

$ mu find --summary-len=3 napoleon m:/archive

1970-01-01T02:00:00 EET Napoleon Bonaparte <nb@example.com> rock on dude
Summary: Le 24 février 1815, la vigie de Notre-Dame de la Garde signala le
trois-mâts le Pharaon, venant de Smyrne, Trieste et Naples. Comme
d'habitude, un pilote côtier partit aussitôt du port, rasa le château

The summary consists of the first n lines of the message with all superfluous whitespace
removed.

Also note the m:/archive parameter in the query. This means that we only match messages in
a maildir called '/archive'.

MORE QUERIES

       Let's  list  a  few  more  queries  that may be interesting; please note that searches for
       message flags, priority and date ranges are only available in mu version 0.9 or later.

       Get all important messages which are signed:
         $ mu find flag:signed prio:high

       Get all messages from Jim without an attachment:
         $ mu find from:jim AND NOT flag:attach

       Get all messages where Jack is in one of the contact fields:
         $ mu find contact:jack
       This uses the special contact: pseudo-field which matches (from, to, cc and bcc).

       Get all messages in the Sent Items folder about yoghurt:
        $mu find maildir:'/Sent Items' yoghurt
       Note how we need to quote search terms that include spaces.

       Get all unread messages where the subject mentions Ångström:
         $ mu find subject:Ångström flag:unread
       which is equivalent to:
         $ mu find subject:angstrom flag:unread
       because does mu is case-insensitive and accent-insensitive.

       Get all unread messages between March 2002 and August 2003 about some bird (or  a  Swedish
       rock band):
         $ mu find date:20020301..20030831 nightingale flag:unread

       Get all messages received today:
         $ mu find date:today..now

       Get all messages we got in the last two weeks about emacs:
         $ mu find date:2w..now emacs

       Another powerful feature (since 0.9.6) are wildcard searches, where you can search for the
       last n characters in a word. For example, you can search for:
         $ mu find 'subject:soc*'
       and get mails about soccer, Socrates, society, and so on. Note, it's  important  to  quote
       the search query, otherwise the shell will interpret the '*'.

       You  can  also  search  for  messages  with a certain attachment using their filename, for
       example:

         $ mu find 'file:pic*'
       will get you all messages with an attachment starting with 'pic'.

       If you want to find attachments with a certain MIME-type, you can use the following:

       Get all messages with PDF attachments:
         $ mu find mime:application/pdf

       or even:

       Get all messages with image attachments:
         $ mu find 'mime:image/*'

       Note that (1) the '*' wildcard can only be used as the rightmost thing in a search  query,
       and  (2)  that  you  need  to  quote  the  search  term, because otherwise your shell will
       interpret the '*' (expanding it to all files in the current directory -- probably not what
       you want).

DISPLAYING MESSAGES

       We  might  also  want  to display the complete messages instead of the header information.
       This can be done using mu view command. Note that this command does not use the  database;
       you simply provide it the path to a message.

       Therefore,  if you want to display some message from a search query, you'll need its path.
       To get the path (think location) for our first example we can use:

         $ mu find --fields="l" t:julius fruit

       And we'll get someting like:
         /home/someuser/Maildir/archive/cur/1266188485_0.6850.cthulhu:2,
       We can now display this message:

         $ mu view /home/someuser/Maildir/archive/cur/1266188485_0.6850.cthulhu:2,

            From: John Milton <jm@example.com>
            To: Julius Caesar <jc@example.com>
            Subject: Fere libenter homines id quod volunt credunt
            Date: 2008-07-31T21:57:25 EEST

            OF Mans First Disobedience, and the Fruit
            Of that Forbidden Tree, whose mortal tast
            Brought Death into the World, and all our woe,
            [...]

FINDING CONTACTS

       While mu find searches for messages, there is also mu cfind to  find  contacts,  that  is,
       names + addresses. Without any search expression, mu cfind lists all of your contacts.

         $ mu cfind julius

       will  find all contacts with 'julius' in either name or e-mail address. Note that mu cfind
       accepts a regular expression.

       mu cfind also supports a --format=-parameter, which  sets  the  output  to  some  specific
       format,  so  the results can be imported into another program. For example, to export your
       contact information to a mutt address book file, you can use something like:

         $ mu cfind --format=mutt-alias > ~/mutt-aliases

       Then, you can use them in mutt if you add something like  source  ~/mutt-aliases  to  your
       muttrc.

AUTHOR

       Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>