Searching with mailpie
======================
:Author: Jeff Epler
:Email:  jepler@unpythonic.net

The script `mailpie-search` is used for searching.  `mailpie-search
\--help` shows a summary of commandline arguments.

Mailpie uses the swish-e full-text indexer.  Most of the ways to search
using swish-e are supported.  However, there are a few differences in
commandline syntax which are discussed below.

== Words and phrases
To search for messages containing the word ``quartz'':
----
$ mailpie-search quartz
----

To search for messages containing the phrase ``blue ox'':
----
$ mailpie-search "blue ox"
----

[NOTE]
========================================================================
In mailpie-search, arguments with embedded whitespace are taken to
be phrases.  This differs from swish, where an extra level of quotes are
required to do phrase searches:
----
$ swish-e -w '"blue ox"'
----
========================================================================

== In Headers
To search for messages with the subject ``quartz'' in the subject line:
----
$ mailpie-search subject=quartz
----

To search for messages with the phrase ``blue ox'' in the subject line:
----
$ mailpie-search subject="blue ox"
----
[NOTE]
========================================================================
The following message headers can searched using the `name=term` syntax:
'subject' 'from' 'to' 'cc' 'bcc' 'list-id'

The entire message headers (not just the ones shown above) can be
searched using `header=term`.
========================================================================

== Multiple terms

To search for messages containing the word ``quartz'' and the phrase ``blue
ox'':
----
$ mailpie-search quartz "blue ox"
----

To search for messages containing the word ``quartz'' or the phrase ``blue
ox'':
----
$ mailpie-search quartz or "blue ox"
----

To search for messages containing the word ``lotus'' and either the word
``quartz'' or the phrase ``blue ox''
----
$ mailpie-search lotus [ quartz or "blue ox" ]
----


== Date ranges
To search for messages sent after April 1 and containing the word
``lotus'':
----
$ mailpie-search --after="april 1" lotus
----

To search for messages sent more than 90 days ago and containing the word
``lotus'':
----
$ mailpie-search --before="90 days ago" lotus
----

For a description of the syntax for dates, read the documentation for
date(1):
----
$ info coreutils date
----
[NOTE]
========================================================================
`\--before=` and `\--after` use the Date header which is controlled by the
sender.  There is no guarantee that this date is accurate, and even if
it is accurate it reflects the time when the message was composed or
sent, not the time when it was received.
========================================================================

[NOTE]
========================================================================
`\--before=` and `\--after=` are always "and"ed with the given search
terms.  At least one other term must be used with `\--before=` and
`\--after=`.
========================================================================

== Integration with various mail clients
=== Mutt
By default, mailpie-search uses mutt to view mailboxes.  It should
require no special configuration in this case.

=== Others
Use the environment variable `MAILPIE_READER` to cause mailpie to invoke
a different mail reader.  The arguments are split into words according
to python `shlex`, which is similar to sh.  After the program name and
flags (if any), a path to a temporary mailbox is given.  When the
invoked program exits, the temporary mailbox is removed.

If you have successfully used mailpie-search with a particular mail
reader, please report what --mailreader= value you used.

// vim:tw=72:sts=4:ts=8:et:sw=4
