| 1 |
grepmail - search mailboxes for a particular email |
| 2 |
|
| 3 |
Grepmail searches a mailbox for a given regular expression, and returns those |
| 4 |
emails that match it. Piped input is allowed, and date and size restrictions |
| 5 |
are supported, as are searches using logical operators. Grepmail also supports |
| 6 |
a variety of compression formats: gzip, bzip2, lzip, and xz. |
| 7 |
|
| 8 |
SOME NOTES |
| 9 |
|
| 10 |
perl version: |
| 11 |
|
| 12 |
If you plan to use advanced pattern features such as "(?>...)", you will need |
| 13 |
to make sure that your version of perl supports them. |
| 14 |
|
| 15 |
Complex queries: |
| 16 |
|
| 17 |
The -E flag allows you to perform complex searches involving logical |
| 18 |
operators. For example, |
| 19 |
|
| 20 |
$email_header =~ /^From: .*\@coppit.org/ && $email =~ /grepmail/i |
| 21 |
|
| 22 |
will find all emails which originate from coppit.org (you must escape the "@" |
| 23 |
sign with a backslash), and which contain the keyword "grepmail" anywhere in |
| 24 |
the message, in any capitalization. |
| 25 |
|
| 26 |
NOTE: -E support is experimental right now. I'm looking for feedback on the |
| 27 |
following: |
| 28 |
|
| 29 |
- Do you like the feature? |
| 30 |
- Do you like the Perl-based syntax? Is there an alternative which is easier? |
| 31 |
- How should date and size constraints be integrated? Should they be |
| 32 |
"variables", a la: "$email =~ /grepmail/ && $date <= 'sep 20 1998' || $size |
| 33 |
> 50000"? |
| 34 |
- Should -i, -h, and -b be supported in conjunction with -E? (Where "-h |
| 35 |
pattern" would mean augmenting the -E pattern with "$email_header =~ |
| 36 |
/pattern/ && ") |
| 37 |
- -S ignores signatures. If/when this feature is implemented for -E, should it |
| 38 |
be "global" for all $email_body matches, or should it be possible to specify |
| 39 |
this for each $email_body match? For example, one can append an "i" modifier |
| 40 |
to an individual pattern match to make it case-insensitive. Should there be |
| 41 |
a standard way of dealing with such "global" pattern matching options on an |
| 42 |
individual pattern match basis? |
| 43 |
|
| 44 |
Message IDs: |
| 45 |
|
| 46 |
NOTE: For emails without message ids, grepmail will use Digest::MD5 to |
| 47 |
compute a hash based on the email header. If you don't have |
| 48 |
Digest::MD5, grepmail will just use the header itself as the messsage |
| 49 |
id. The Digest::MD5 checksum takes a little while to compute, but |
| 50 |
saves a lot of space. Currently there is no easy way to choose space |
| 51 |
over time. Let me know if this is a problem. |
| 52 |
|
| 53 |
|
| 54 |
MODULE DEPENDENCIES |
| 55 |
|
| 56 |
To use this program, you will need to install: |
| 57 |
|
| 58 |
- Mail::Mbox::MessageParser: required |
| 59 |
- Date::Parse: required |
| 60 |
- Date::Manip: required if you want to search using complex date |
| 61 |
specifications (-d) |
| 62 |
- Digest::MD5: not required, but can help grepmail use less memory if |
| 63 |
you are checking for unique emails (-u) and your emails don't have a |
| 64 |
Message-Id header |
| 65 |
|
| 66 |
To test this module, you will need to install: |
| 67 |
|
| 68 |
- Test::More |
| 69 |
|
| 70 |
|
| 71 |
INSTALLATION |
| 72 |
|
| 73 |
=> On Non-Windows (Unix/Cygwin/etc.) systems: |
| 74 |
|
| 75 |
To install this package, change to the directory where you unarchived this |
| 76 |
distribution and type the following: |
| 77 |
|
| 78 |
perl Makefile.PL |
| 79 |
make |
| 80 |
make test |
| 81 |
make install |
| 82 |
|
| 83 |
You can install this package into a non-default location by appending one of |
| 84 |
the following to the "perl Makefile.PL" command: |
| 85 |
|
| 86 |
- "PREFIX=/installation/path" (for installation into a custom location), |
| 87 |
- "INSTALLDIRS=site" (for installation into site-specific Perl directories) |
| 88 |
- "INSTALLDIRS=perl" (for installation into standard Perl directories). |
| 89 |
|
| 90 |
If make test fails, please see the INSTALLATION PROBLEMS section below. |
| 91 |
|
| 92 |
=> On Windows systems: |
| 93 |
|
| 94 |
- Just copy "grepmail" to a place in your path. You may want to rename it |
| 95 |
"grepmail.pl" if you've associated .pl files with perl.exe. |
| 96 |
|
| 97 |
|
| 98 |
CONFIGURATION |
| 99 |
|
| 100 |
You may want to set your MAIL environment variable so that grepmail will know |
| 101 |
the default location to search for mailboxes. |
| 102 |
|
| 103 |
If you are terribly concerned about performance, you may want to modify the |
| 104 |
value of the variable READ_CHUNK_SIZE located in the code. This variable |
| 105 |
controls how much text is read from the mailbox at a time. If the value is set |
| 106 |
to 0, the entire file is read into memory. (There is no user-visible option |
| 107 |
for setting this value.) You may also want to hack the code to not use |
| 108 |
Digest::MD5, thereby trading space for time. |
| 109 |
|
| 110 |
If you frequently use the same set of flags, you may wish to alias "grepmail" |
| 111 |
to "grepmail -flags" within your command interpreter (shell). See the |
| 112 |
documentation for your shell for details on how to do this. |
| 113 |
|
| 114 |
|
| 115 |
INSTALLATION PROBLEMS |
| 116 |
|
| 117 |
If "make test" fails, run |
| 118 |
|
| 119 |
make test TEST_VERBOSE=1 |
| 120 |
|
| 121 |
and see which test(s) are failing. Please email, to the address below, the |
| 122 |
output files for the test. Also email the output of running the particular |
| 123 |
subtest with the -D flag. e.g.: |
| 124 |
|
| 125 |
./blib/script/grepmail -D --help > test_name.debug |
| 126 |
|
| 127 |
If the first date_manip test case fails, you are in a timezone that |
| 128 |
Date::Manip does not yet support. You will need to contact the author of |
| 129 |
Date::Manip. |
| 130 |
|
| 131 |
For other bugs, see the section REPORTING BUGS below. |
| 132 |
|
| 133 |
|
| 134 |
DOCUMENTATION |
| 135 |
|
| 136 |
Just "perldoc grepmail". After installation on Unix systems, you can also do |
| 137 |
"man grepmail". |
| 138 |
|
| 139 |
|
| 140 |
RESOURCES |
| 141 |
|
| 142 |
The CPAN Page: |
| 143 |
http://search.cpan.org/dist/grepmail/ |
| 144 |
|
| 145 |
The GitHub page: |
| 146 |
https://github.com/coppit/grepmail/ |
| 147 |
|
| 148 |
Bug and feature tracking: |
| 149 |
http://rt.cpan.org/Public/Dist/Display.html?Name=grepmail |
| 150 |
|
| 151 |
When reporting a bug, please attach the output of running grepmail with the -D |
| 152 |
switch. If the bug is related to processing of a particular mailbox, try to |
| 153 |
trim the mailbox to the smallest set of emails that still exhibit the problem. |
| 154 |
Then use the "anonymize_mailbox" program that comes with grepmail to remove |
| 155 |
any sensitive information, and attach the mailbox to the bug report. |
| 156 |
|
| 157 |
|
| 158 |
COPYRIGHT |
| 159 |
|
| 160 |
Copyright (c) 1998-Sep 1 2000 Broc Seib. Copyright (c) Sep 1 2000-2015 David |
| 161 |
Coppit. All rights reserved, save those granted by the license. See the file |
| 162 |
LICENSE for licensing terms. |
| 163 |
|
| 164 |
|
| 165 |
AUTHOR |
| 166 |
|
| 167 |
David Coppit <[email protected]> |