GREPMAIL(1p)

📦
version 5.3111 · 4 versions
, in debian trixie, ubuntu noble, ubuntu questing

💖 GREPMAIL(1p) 💖

okay bestie, welcome to GREPMAIL(1p) — straight out of the User Contributed Perl Documentation section, and yes it's giving legend behavior. grab a snack, we're doing this together 🍓

✨ NAME ✨

grepmail — search mailboxes for mail matching a regular expression 🔍💌

🌸 SYNOPSIS 🌸

grepmail [--help|--version] [-abBDFhHilLmrRuvVw] [-C <cache-file>]
  [-j <status>] [-s <sizespec>] [-d <date-specification>]
  [-X <signature-pattern>] [-Y <header-pattern>]
  [[-e] <pattern>|-E <expr>|-f <pattern-file>] <files...>

🦋 DESCRIPTION 🦋

so basically grepmail goes looking through your mail messages for a pattern, and then prints the messages it found on standard out. that's it. that's the whole vibe ✨

by default, grepmail looks in both the header and the body for the pattern you gave it. thorough queen 💅

when you redirect the output to a file, what you get is another mailbox — which can then be handled by standard User Agents like elm, or even fed as input into another instance of grepmail. it's mailboxes all the way down, no cap 🌀

heads up bestie: at least one of -E, -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. and the -E option can be used to specify complex search expressions involving logical operators (more on that below 👇).

if a mailbox can't be found, grepmail first searches the directory specified by the MAILDIR environment variable (if one is defined), and then searches the $HOME/mail, $HOME/Mail, and $HOME/Mailbox directories. it's persistent. it's dedicated. it's the main character 🫶

👑 OPTIONS AND ARGUMENTS 👑

ngl, a lot of these options and arguments are analogous to those of grep. iconic family lineage 💖

💌 pattern

the pattern to search for in the mail message. it can be any Perl regular expression, but you should quote it on the command line to protect against globbing (that's shell expansion, and she WILL expand on you 😭).

to search for more than one pattern, use the form "(pattern1|pattern2|...)".

note that complex pattern features such as "(?>...)" require that you use a version of perl which supports them. and you can use the pattern "()" to indicate that you do not want to match anything at all — which is genuinely so useful if you just want to initialize the cache without printing any output. sneaky. efficient. obsessed 💅

📬 mailbox

mailboxes must be traditional, UNIX "/bin/mail" mailbox format.

the mailboxes may be compressed by gzip, bzip2, lzip or xz — in which case the associated compression tool must be installed on the system, as well as a recent version of the Mail::Mbox::MessageParser Perl module that supports the format. no module, no compression party, sorry 🎀

if no mailbox is specified, it takes input from stdin, which can be compressed or not.

fr fr important: grepmail's behavior is undefined when ASCII and binary data is piped together as input. do not do that. just don't. 💀

the options, one by one, slay by slay ✨

  • -a — use arrival date instead of sent date.
  • -b — asserts that the pattern must match in the body of the email.
  • -B — print the body, but with only minimal headers: 'From ', 'From:', 'Subject:', 'Date:'. this flag can be used with -H, in which case it will print only short headers and no email bodies.
  • -C — specifies the location of the cache file. the default is $HOME/.grepmail-cache.
  • -D — enable debug mode, which prints diagnostic messages. (she's telling you everything, bestie 🗣️)
  • -e — explicitly specify the search pattern. this is useful for specifying patterns that begin with -, which would otherwise be interpreted as a flag. protecting you from your own chaos 🫶
  • -f — obtain patterns from FILE, one per line. the empty file contains zero patterns, and therefore matches nothing. (zero patterns = zero matches, math is math 🧮)
  • -F — force grepmail to process all files and streams as though they were mailboxes. (i.e. skip checks for non-mailbox ASCII files or binary files that don't look like they are compressed using known schemes.)
  • -h — asserts that the pattern must match in the header of the email.
  • -H — print the header but not the body of matching emails.
  • -i — make the search case-insensitive (by analogy to grep -i).
  • -j — asserts that the email "Status:" header must contain the given flags. order and case are not important, so use -j AR or -j ra to search for emails which have been read and answered. lowercase? uppercase? she does not care 💅
  • -l — output the names of files having an email matching the expression (by analogy to grep -l).
  • -L — follow symbolic links. (implies -R)
  • -M — causes grepmail to ignore non-text MIME attachments. this removes false positives resulting from binaries encoded as ASCII attachments. bye bye fake matches 👋
  • -m — append "X-Mailfolder: <folder>" to all email headers, indicating which folder contained the matched email. receipts included 🧾
  • -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. yes that's a little weird, no it's not a typo 🙈
  • -q — quiet mode. suppress the output of warning messages about non-mailbox files, directories, etc. shhh 🤫
  • -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. down down down we go 🌀
  • -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. plot twist 🔄
  • -V — print the version and exit.
  • -w — search for only those lines which contain the pattern as part of a word group. that is, the start of the pattern must match the start of a word, and the end of the pattern must match the end of a word. (note that the start and end need not be for the same word.)

if you're familiar with Perl regular expressions, this flag simply puts a "\b" before and after the search pattern. cute little word boundaries 🎀

  • -X — specify a regular expression for the signature separator. by default this pattern is '^-- $'.

🌈 -d — date specs, the whole thing

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. ghost emails, found 👻

date specifications without times are interpreted as having a time of midnight of that day (which is the morning), except for "after" and "since" specifications, which are interpreted as midnight of the following day. for example, "between today and tomorrow" is the same as simply "today", and returns emails whose date has the current day. ("now" is interpreted as "today".) the date specification "after July 5th" will return emails whose date is midnight July 6th or later. the math is mathing ✨

💜 -E — complex search expressions

specify a complex search expression using logical operators. the current syntax allows the user to specify search expressions using Perl syntax. three values can be used: $email (the entire email message), $email_header (just the header), or $email_body (just the body). a search is specified in the form "$email =~ /pattern/", and multiple searches can be combined using "&&" and "||" for "and" and "or". build-a-search workshop 🛠️✨

for example, the expression

$email_header =~ /^From: .*\@coppit.org/ && $email =~ /grepmail/i

will find all emails which originate from coppit.org (you must escape the "@" sign with a backslash), and which contain the keyword "grepmail" anywhere in the message, in any capitalization. look at her go 😌

not compatible, periodt: -E is incompatible with -b, -h, and -e. -i, -M, -S, and -Y have not yet been implemented.
NOTE: the syntax of search expressions may change in the future. in particular, support for size, date, and other constraints may be added. the syntax may also be simplified in order to make expression formation easier to use (and perhaps at the expense of reduced functionality). so like… screenshot this, bestie 📸

🍓 -s — size specs

return emails which match the size (in bytes) specified with this flag. note that this size includes the length of the header.

size constraints must be of the form of:

  • 12345: match size of exactly 12345
  • <12345, <=12345, >12345, >=12345: match size less than, less than or equal, greater than, or greater than or equal to 12345
  • 10000-12345: match size between 10000 and 12345 inclusive

🧚 -Y — header patterns

specify a pattern which indicates specific headers to be searched. the search will automatically treat headers which span multiple lines as one long line. this flag implies -h.

in the style of procmail, special strings in the pattern will be expanded as follows:

if the regular expression contains "^TO:" it will be substituted by

^((Original-)?(Resent-)?(To|Cc|Bcc)|(X-Envelope|Apparently(-Resent)?)-To):

which should match all headers with destination addresses.

if the regular expression contains "^FROM_DAEMON:" it will be substituted by

(^(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 ][^<)]*(\(.*\).*)?)?

which should catch mails coming from most daemons.

if the regular expression contains "^FROM_MAILER:" it will be substituted by

(^(((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][^<)]*(\(.*\).*)?)?$([^>]|$))

(a stripped down version of "^FROM_DAEMON:"), which should catch mails coming from most mailer-daemons.

so, to search for all emails to or from "Andy":

grepmail -Y '(^TO:|^From:)' Andy mailbox

💖 the rest

  • --help — print a help message summarizing the usage.
  • -- — all arguments following -- are treated as mail folders. everything after is just folders, no more flags, we're done with options 💅

…and that's part one, bestie!! there's more coming so don't go anywhere 🫶✨

✨ EXAMPLES ✨

okay so like, examples? we love a practical demo. here's every single one from the page, no cap. 💅

💖 Count the number of emails

(. matches every email.)

grepmail -r . sent-mail

📚 Get all email between 2000 and 3000 bytes about books

grepmail books -s 2000-3000 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 1998" sent-mail

📅 Get all email that you mailed before the first of June 1998 that pertains to research

grepmail research -d "before 6/1/98" sent-mail

🚫 Get all email you received since 8/20/98 that wasn't about research or your job, ignoring case

grepmail -iv "(research|job)" -d "since 8/20/98" saved-mail

🧜 Get all email about mime but not about Netscape. Constrain the search to match the body, since most headers contain the text "mime"

grepmail -b mime saved-mail | grepmail Netscape -v
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*
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

📬 Search for all emails to or from an address (taking into account wrapped headers and different header names)

grepmail -Y '(^TO:|^From:)' my@email.address saved-mail

👮 Find all emails from postmasters

grepmail -Y '^FROM_MAILER:' . saved-mail

🌸 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. 🧠💖

🦋 ENVIRONMENT 🦋

the MAILDIR environment variable can be used to specify the default mail directory. this directory will be searched if the specified mailbox can not be found directly.

the HOME environment variable is also used to find mailboxes if they can not be found directly. it is also used to store grepmail state information such as its cache file.

💀 BUGS AND LIMITATIONS 💀

Patterns containing $ may cause problems

currently I look for $ followed by a non-word character and replace it with the line ending for the current file (either \n or \r\n). this may cause problems with complex patterns specified with -E, but I'm not aware of any. 😭

Mails without bodies cause problems

according to RFC 822, mail messages need not have message bodies. I've found and removed one bug related to this. I'm not sure if there are others. 🙈

Complex single-point dates not parsed correctly

if you specify a point date like "September 1, 2004", grepmail creates a date range that includes the entire day of September 1, 2004. if you specify a complex point date such as "today", "1st Monday in July", or "9/1/2004 at 0:00" grepmail may parse the time incorrectly.

the reason for this problem is that Date::Manip, as of version 5.42, forces default values for parsed dates and times. this means that grepmail has a hard time determining whether the user supplied certain time/date fields. (e.g. Did Date::Manip provide a default time of 0:00, or did the user specify it?) grepmail tries to work around this problem, but the workaround is inherently incomplete in some rare cases.

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. 💅

📜 LICENSE 📜

this code is distributed under the GNU General Public License (GPL) Version 2. see the file LICENSE in the distribution for details. 🫶

👑 AUTHOR 👑

David Coppit <david@coppit.org> — iconic. 💖

🌈 SEE ALSO 🌈

check out: elm(1), mail(1), grep(1), perl(1), printmail(1), Mail::Internet(3), procmailrc(5). also: Crocker, D. H., Standard for the Format of Arpa Internet Text Messages, RFC 822. 📚

and that's the whole page, bestie! this is from perl v5.36.0, dated 2023-09-24, and it's GREPMAIL(1p). slay. 💅✨

📦 where this page comes from