1GREPMAIL(1) User Contributed Perl Documentation GREPMAIL(1)
2
6 grepmail - search mailboxes for mail matching a regular expression
7
9 grepmail [--help⎪--version] [-abBDFhHilLmrRuvVw] [-C <cache-file>]
10 [-j <status>] [-s <sizespec>] [-d <date-specification>]
11 [-X <signature-pattern>] [-Y <header-pattern>]
12 [[-e] <pattern>⎪-E <expr>⎪-f <pattern-file>] <files...>
13
15 grepmail looks for mail messages containing a pattern, and prints the
16 resulting messages on standard out.
17 By default grepmail looks in both header and body for the specified
19 pattern.
20 When redirected to a file, the result is another mailbox, which can,
22 in turn, be handled by standard User Agents, such as elm, or even
23 used as input for another instance of grepmail.
24 At least one of -E, -e, -d, -s, or -u must be specified. The pattern
26 is optional if -d, -s, and/or -u is used. The -e flag is optional if
27 there is no file whose name is the pattern. The -E option can be used
28 to specify complex search expressions involving logical operators.
29 (See below.)
30 If a mailbox can not be found, grepmail first searches the directory
32 specified by the MAILDIR environment variable (if one is defined),
33 then searches the $HOME/mail, $HOME/Mail, and $HOME/Mailbox directo‐
34 ries.
35
37 Many of the options and arguments are analogous to those of grep.
38 pattern
40 The pattern to search for in the mail message. May be any Perl regu‐
41 lar expression, but should be quoted on the command line to protect
42 against globbing (shell expansion). To search for more than one pat‐
43 tern, use the form "(pattern1⎪pattern2⎪...)".
44 Note that complex pattern features such as "(?>...)" require that you
46 use a version of perl which supports them. You can use the pattern
47 "()" to indicate that you do not want to match anything. This is use‐
48 ful if you want to initialize the cache without printing any output.
49 mailbox
51 Mailboxes must be traditional, UNIX "/bin/mail" mailbox format. The
52 mailboxes may be compressed by gzip, or bzip2, in which case gunzip,
53 or bzip2 must be installed on the system.
54 If no mailbox is specified, takes input from stdin, which can be com‐
56 pressed or not. grepmail's behavior is undefined when ASCII and
57 binary data is piped together as input.
58 -a
60 Use arrival date instead of sent date.
61 -b
63 Asserts that the pattern must match in the body of the email.
64 -B
66 Print the body but with only minimal ('From ', 'From:', 'Subject:',
67 'Date:') headers. This flag can be used with -H, in which case it
68 will print only short headers and no email bodies.
69 -C
71 Specifies the location of the cache file. The default is $HOME/.grep‐
72 mail-cache.
73 -D
75 Enable debug mode, which prints diagnostic messages.
76 -d
78 Date specifications must be of the form of:
79 - a date like "today", "yesterday", "5/18/93", "5 days ago", "5
80 weeks ago",
81 - OR "before", "after", or "since", followed by a date as defined
82 above,
83 - OR "between <date> and <date>", where <date> is defined as above.
84 Simple date expressions will first be parsed by Date::Parse. If this
86 fails, grepmail will attempt to parse the date with Date::Manip, if
87 the module is installed on the system. Use an empty pattern (i.e. -d
88 "") to find emails without a "Date: ..." line in the header.
89 Date specifications without times are interpreted as having a time of
91 midnight of that day (which is the morning), except for "after" and
92 "since" specifications, which are interpreted as midnight of the fol‐
93 lowing day. For example, "between today and tomorrow" is the same as
94 simply "today", and returns emails whose date has the current day.
95 ("now" is interpreted as "today".) The date specification "after July
96 5th" will return emails whose date is midnight July 6th or later.
97 -E
99 Specify a complex search expression using logical operators. The cur‐
100 rent syntax allows the user to specify search expressions using Perl
101 syntax. Three values can be used: $email (the entire email message),
102 $email_header (just the header), or $email_body (just the body). A
103 search is specified in the form "$email =~ /pattern/", and multiple
104 searches can be combined using "&&" and "⎪⎪" for "and" and "or".
105 For example, the expression
107 $email_header =~ /^From: .*\@coppit.org/ && $email =~ /grepmail/i
109 will find all emails which originate from coppit.org (you must escape
111 the "@" sign with a backslash), and which contain the keyword "grep‐
112 mail" anywhere in the message, in any capitalization.
113 -E is incompatible with -b, -h, and -e. -i, -M, -S, and -Y have not
115 yet been implemented.
116 NOTE: The syntax of search expressions may change in the future. In
118 particular, support for size, date, and other constraints may be
119 added. The syntax may also be simplified in order to make expression
120 formation easier to use (and perhaps at the expense of reduced func‐
121 tionality).
122 -e
124 Explicitly specify the search pattern. This is useful for specifying
125 patterns that begin with "-", which would otherwise be interpreted as
126 a flag.
127 -f
129 Obtain patterns from FILE, one per line. The empty file contains
130 zero patterns, and therefore matches nothing.
131 -F
133 Force grepmail to process all files and streams as though they were
134 mailboxes. (i.e. Skip checks for non-mailbox ASCII files or binary
135 files that don't look like they are compressed using known schemes.)
136 -h
138 Asserts that the pattern must match in the header of the email.
139 -H
141 Print the header but not body of matching emails.
142 -i
144 Make the search case-insensitive (by analogy to grep -i).
145 -j
147 Asserts that the email "Status:" header must contain the given flags.
148 Order and case are not important, so use -j AR or -j ra to search for
149 emails which have been read and answered.
150 -l
152 Output the names of files having an email matching the expression,
153 (by analogy to grep -l).
154 -L
156 Follow symbolic links. (Implies -R)
157 -M
159 Causes grepmail to ignore non-text MIME attachments. This removes
160 false positives resulting from binaries encoded as ASCII attachments.
161 -m
163 Append "X-Mailfolder: <folder>" to all email headers, indicating
164 which folder contained the matched email.
165 -n
167 Prefix each line with line number information. If multiple files are
168 specified, the filename will precede the line number. NOTE: When used
169 in conjunction with -m, the X-Mailfolder header has the same line
170 number as the next (blank) line.
171 -q
173 Quiet mode. Suppress the output of warning messages about non-mailbox
174 files, directories, etc.
175 -r
177 Generate a report of the names of the files containing emails match‐
178 ing the expression, along with a count of the number of matching
179 emails.
180 -R
182 Causes grepmail to recurse any directories encountered.
183 -s
185 Return emails which match the size (in bytes) specified with this
186 flag. Note that this size includes the length of the header.
187 Size constraints must be of the form of:
189 - 12345: match size of exactly 12345
190 - <12345, <=12345, >12345, >=12345: match size less than, less than
191 or equal,
192 greater than, or greater than or equal to 12345
193 - 10000-12345: match size between 10000 and 12345 inclusive
194 -S
196 Ignore signatures. The signature consists of everything after a line
197 consisting of "-- ".
198 -u
200 Output only unique emails, by analogy to sort -u. Grepmail determines
201 email uniqueness by the Message-ID header.
202 -v
204 Invert the sense of the search, by analogy to grep -v. This results
205 in the set of emails printed being the complement of those that would
206 be printed without the -v switch.
207 -V
209 Print the version and exit.
210 -w
212 Search for only those lines which contain the pattern as part of a
213 word group. That is, the start of the pattern must match the start
214 of a word, and the end of the pattern must match the end of a word.
215 (Note that the start and end need not be for the same word.)
216 If you are familiar with Perl regular expressions, this flag simply
218 puts a "\b" before and after the search pattern.
219 -X
221 Specify a regular expression for the signature separator. By default
222 this pattern is '^-- $'.
223 -Y
225 Specify a pattern which indicates specific headers to be searched.
226 The search will automatically treat headers which span multiple lines
227 as one long line. This flag implies -h.
228 In the style of procmail, special strings in the pattern will be
230 expanded as follows:
231 If the regular expression contains "^TO:" it will be substituted by
233 ^((Original-)?(Resent-)?(To⎪Cc⎪Bcc)⎪(X-Envelope⎪Apparently(-Resent)?)-To):
235 which should match all headers with destination addresses.
237 If the regular expression contains "^FROM_DAEMON:" it will be sub‐
239 stituted by
240 (^(Mailing-List:⎪Precedence:.*(junk⎪bulk⎪list)⎪To: Multiple recipients of ⎪(((Resent-)?(From⎪Sender)⎪X-Envelope-From):⎪>?From )([^>]*[^(.%@a-z0-9])?(Post(ma?(st(e?r)?⎪n)⎪office)⎪(send)?Mail(er)?⎪daemon⎪m(mdf⎪ajordomo)⎪n?uucp⎪LIST(SERV⎪proc)⎪NETSERV⎪o(wner⎪ps)⎪r(e(quest⎪sponse)⎪oot)⎪b(ounce⎪bs\.smtp)⎪echo⎪mirror⎪s(erv(ices?⎪er)⎪mtp(error)?⎪ystem)⎪A(dmin(istrator)?⎪MMGR⎪utoanswer))(([^).!:a-z0-9][-_a-z0-9]*)?[%@>\t ][^<)]*(\(.*\).*)?)?
242 which should catch mails coming from most daemons.
244 If the regular expression contains "^FROM_MAILER:" it will be sub‐
246 stituted by
247 (^(((Resent-)?(From⎪Sender)⎪X-Envelope-From):⎪>?From)([^>]*[^(.%@a-z0-9])?(Post(ma(st(er)?⎪n)⎪office)⎪(send)?Mail(er)?⎪daemon⎪mmdf⎪n?uucp⎪ops⎪r(esponse⎪oot)⎪(bbs\.)?smtp(error)?⎪s(erv(ices?⎪er)⎪ystem)⎪A(dmin(istrator)?⎪MMGR))(([^).!:a-z0-9][-_a-z0-9]*)?[%@>\t][^<)]*(\(.*\).*)?)?$([^>]⎪$))
249 (a stripped down version of "^FROM_DAEMON:"), which should catch
251 mails coming from most mailer-daemons.
252 So, to search for all emails to or from "Andy":
254 grepmail -Y '(^TO:⎪^From:)' Andy mailbox
256 --help
258 Print a help message summarizing the usage.
259 --
261 All arguments following -- are treated as mail folders.
262
264 Count the number of emails. ("." matches every email.)
265 grepmail -r . sent-mail
267 Get all email between 2000 and 3000 bytes about books
269 grepmail books -s 2000-3000 sent-mail
271 Get all email that you mailed yesterday
273 grepmail -d yesterday sent-mail
275 Get all email that you mailed before the first thursday in June 1998
277 that pertains to research (requires Date::Manip):
278 grepmail research -d "before 1st thursday in June 1992" sent-mail
280 Get all email that you mailed before the first of June 1998 that per‐
282 tains to research:
283 grepmail research -d "before 6/1/92" sent-mail
285 Get all email you received since 8/20/98 that wasn't about research or
287 your job, ignoring case:
288 grepmail -iv "(research⎪job)" -d "since 8/20/98" saved-mail
290 Get all email about mime but not about Netscape. Constrain the search
292 to match the body, since most headers contain the text "mime":
293 grepmail -b mime saved-mail ⎪ grepmail Netscape -v
295 Print a list of all mailboxes containing a message from Rodney. Con‐
297 strain the search to the headers, since quoted emails may match the
298 pattern:
299 grepmail -hl "^From.*Rodney" saved-mail*
301 Find all emails with the text "Pilot" in both the header and the body:
303 grepmail -hb "Pilot" saved-mail*
305 Print a count of the number of messages about grepmail in all saved-
307 mail mailboxes:
308 grepmail -br grepmail saved-mail*
310 Remove any duplicates from a mailbox:
312 grepmail -u saved-mail
314 Convert a Gnus mailbox to mbox format:
316 grepmail . gnus-mailbox-dir/* > mbox
318 Search for all emails to or from an address (taking into account
320 wrapped headers and different header names):
321 grepmail -Y '(^TO:⎪^From:)' my@email.address saved-mail
323 Find all emails from postmasters:
325 grepmail -Y '^FROM_MAILER:' . saved-mail
327
329 grepmail will not create temporary files while decompressing compressed
330 archives. The last version to do this was 3.5. While the new design
331 uses more memory, the code is much simpler, and there is less chance
332 that email can be read by malicious third parties. Memory usage is
333 determined by the size of the largest email message in the mailbox.
334
336 The MAILDIR environment variable can be used to specify the default
337 mail directory. This directory will be searched if the specified mail‐
338 box can not be found directly.
339 The HOME environment variable is also used to find mailboxes if they
341 can not be found directly. It is also used to store grepmail state
342 information such as its cache file.
343
345 Patterns containing "$" may cause problems
346 Currently I look for "$" followed by a non-word character and replace
347 it with the line ending for the current file (either "\n" or "\r\n").
348 This may cause problems with complex patterns specified with -E, but
349 I'm not aware of any.
350 Mails without bodies cause problems
352 According to RFC 822, mail messages need not have message bodies.
353 I've found and removed one bug related to this. I'm not sure if there
354 are others.
355 Complex single-point dates not parsed correctly
357 If you specify a point date like "September 1, 2004", grepmail cre‐
358 ates a date range that includes the entire day of September 1, 2004.
359 If you specify a complex point date such as "today", "1st Monday in
360 July", or "9/1/2004 at 0:00" grepmail may parse the time incorrectly.
361 The reason for this problem is that Date::Manip, as of version 5.42,
363 forces default values for parsed dates and times. This means that
364 grepmail has a hard time determining whether the user supplied cer‐
365 tain time/date fields. (e.g. Did Date::Manip provide a default time
366 of 0:00, or did the user specify it?) grepmail tries to work around
367 this problem, but the workaround is inherently incomplete in some
368 rare cases.
369 File names that look like flags cause problems.
371 In some special circumstances, grepmail will be confused by files
372 whose names look like flags. In such cases, use the -e flag to spec‐
373 ify the search pattern.
374
376 David Coppit, <david@coppit.org>, http://coppit.org/
377
379 elm(1), mail(1), grep(1), perl(1), printmail(1), Mail::Internet(3),
380 procmailrc(5). Crocker, D. H., Standard for the Format of Arpa Inter‐
381 net Text Messages, RFC 822.
382perl v5.8.8 2007-03-01 GREPMAIL(1)