grepmail looks for mail messages containing a pattern, and prints the
resulting messages on standard out.
By default grepmail looks in both header and body for the specified pattern.
When redirected to a file, the result is another mailbox, which can, in turn,
be handled by standard User Agents, such as elm, or even used as input for
another instance of grepmail.
At least one of -e, -d, -s, or -u must be specified. The pattern
is optional if -d, -s, and/or -u is used. The -e flag is optional
if there is no file whose name is the pattern.
OPTIONS AND ARGUMENTS
Many of the options and arguments are analogous to those of grep.
pattern
The pattern to search for in the mail message. May be any Perl regular
expression, but should be quoted on the command line to protect against
globbing (shell expansion). To search for more than one pattern, use the form
``(pattern1|pattern2|...)''.
mailbox
Mailboxes must be traditional, UNIX "/bin/mail" mailbox format. The
mailboxes may be compressed by gzip, tzip, or bzip2, in which case
gunzip, tzip, or bzip2 must be installed on the system.
If no mailbox is specified, takes input from stdin, which can be compressed or
not. grepmail's behavior is undefined when ASCII and binary data is piped
together as input.
-a
Use arrival date instead of sent date.
-b
Asserts that the pattern must match in the body of the email. (Not compatible
with -B.)
-D
Enable debug mode, which prints diagnostic messages.
-d
Date specifications must be of the form of:
- a date like ``today'', ``yesterday'', ``5/18/93'', ``5 days ago'', ``5 weeks ago'',
- OR ``before'', ``after'', or ``since'', followed by a date as defined above,
- OR ``between <date> and <date>'', where <date> is defined as above.
Simple date expressions will first be parsed by Date::Parse. If this fails,
grepmail will attempt to parse the date with Date::Manip, if the module is
installed on the system. Use an empty pattern (i.e. -d "") to find emails
without a ``Date: ...'' line in the header.
-e
Explicitly specify the search pattern. This is useful for specifying patterns
that begin with ``-'', which would otherwise be interpreted as a flag.
-h
Asserts that the pattern must match in the header of the email.
-H
Print the header but not body of matching emails.
-i
Make the search case-insensitive (by analogy to grep -i).
-l
Output the names of files having an email matching the expression, (by analogy
to grep -l).
-M
Causes grepmail to ignore non-text MIME attachments. This removes false
positives resulting from binaries encoded as ASCII attachments.
-m
Append ``X-Mailfolder: <folder>'' to all email headers, indicating which folder
contained the matched email.
-n
Prefix each line with line number information. If multiple files are
specified, the filename will precede the line number. NOTE: When used in
conjunction with -m, the X-Mailfolder header has the same line number as
the next (blank) line.
-q
Quiet mode. Suppress the output of warning messages about non-mailbox files,
directories, etc.
-r
Generate a report of the names of the files containing emails matching the
expression, along with a count of the number of matching emails.
-R
Causes grepmail to recurse any directories encountered.
-s
Return emails smaller than the size (in bytes) specified with this flag.
-S
Ignore signatures. The signature consists of everything after a line
consisting of ``-- ''.
-u
Output only unique emails, by analogy to sort -u. Grepmail determines email
uniqueness by the Message-ID header.
-v
Invert the sense of the search, by analogy to grep -v. This results in the
set of emails printed being the complement of those that would be printed
without the -v switch.
-Z
By default, grepmail uses the Mail::Folder::FastReader module if it is on the
system. This switch tells it to use the slower Perl implementation instead.
---help
Print a help message summarizing the usage.
EXAMPLES
Count the number of emails. (``.'' matches every email.)
grepmail -r . sent-mail
Get all email larger than 2000 bytes about books
grepmail books -s 2000 sent-mail
Get all email that you mailed yesterday
grepmail -d yesterday sent-mail
Get all email that you mailed before the first thursday in June 1998 that
pertains to research (requires Date::Manip):
grepmail research -d "before 1st thursday in June 1992" sent-mail
Get all email that you mailed before the first of June 1998 that
pertains to research:
grepmail research -d "before 6/1/92" sent-mail
Get all email you received since 8/20/98 that wasn't about research or your
job, ignoring case:
Print a list of all mailboxes containing a message from Rodney. Constrain the
search to the headers, since quoted emails may match the pattern:
grepmail -hl "^From.*Rodney" saved-mail*
Find all emails with the text ``Pilot'' in both the header and the body:
grepmail -hb "Pilot" saved-mail*
Print a count of the number of messages about grepmail in all saved-mail
mailboxes:
grepmail -br grepmail saved-mail*
Remove any duplicates from a mailbox:
grepmail -u saved-mail
Convert a Gnus mailbox to mbox format:
grepmail . gnus-mailbox-dir/* > mbox
FILES
grepmail will not create temporary files while decompressing compressed
archives. The last version to do this was 3.5. While the new design uses
more memory, the code is much simpler, and there is less chance that email
can be read by malicious third parties. Memory usage is determined by the size
of the largest email message in the mailbox.
BUGS AND LIMITATIONS
Test case 1 fails on some platforms
Bug not squashed yet. Any info would be appreciated.
File names with special characters cause problems.
grepmail uses the shell to invoke the decompression filters. If the filename
contains single quotes, ampersands, backslashes, etc, this can cause problems.
This bug is not a high priority --- please send email if you really need it
fixed.
The fix is to fork the process, opening up a pipe to the child, which starts
the filter process using the multiple argument form of exec (which doesn't
invoke the shell).
File names that look like flags cause problems.
In some special circumstances, grepmail will be confused by files whose names
look like flags. In such cases, use the -e flag to specify the search
pattern.
Error messages when searching compressed files are wrong
grepmail decompresses compressed files and re-invokes itself on them.
As a result, any errors that occur while processing the uncompressed
file will result in messages that do not reference the original
compressed file. For example:
