Mail::...h::Grep(3pm)

💅 Mail::Box::Search::Grep — the grep-but-for-mailboxes era

okay bestie so, picture this: you have a whole mailbox and you just want to find some text in it. That's this. That's the whole vibe. It lives in the User Contributed Perl Documentation manual group, and honestly? It ate. 🍓

---

🌸 NAME

Mail::Box::Search::Grep — select messages within a mail box like grep does ✨

🧬 INHERITANCE

Mail::Box::Search::Grep
  is a Mail::Box::Search
  is a Mail::Reporter

📜 SYNOPSIS

use Mail::Box::Manager;
my $mgr    = Mail::Box::Manager->new;
my $folder = $mgr->open('Inbox');

my $filter = Mail::Box::Search::Grep->new(
   label => 'selected',
   in => 'BODY', match => qr/abc?d*e/
);

my @msgs   = $filter->search($folder);

my $filter = Mail::Box::Search::Grep->new(
  field => 'To',
  match => $my_email,
);

if($filter->search($message)) {...}

💖 DESCRIPTION

So the mission here is: try to find some text strings in the header and footer of messages. And there are so many ways to narrow it down — you can limit the search to certain header fields, to the whole header, only the body, the whole entire message, and honestly even binary multiparts are on the menu. Options? We got options. 🌈

Now, the name grep? It's derived from the UNIX tool grep, which stands for: "Get Regular Expression and Print". And yes you can search using regular expressions (the Perl way of them, obviously 🧚), but the "print" part? Not required. You do you, boo.

Extends "DESCRIPTION" in Mail::Box::Search.

🛠️ METHODS

Extends "METHODS" in Mail::Box::Search.

🎀 Constructors

Extends "Constructors" in Mail::Box::Search.

$class->new(%options)

Create a UNIX-grep like search filter. Improves base, see "METHODS" in Mail::Box::Search. 👑

 -Option    --Defined in       --Default
  binaries    Mail::Box::Search  false
  decode      Mail::Box::Search  true
  delayed     Mail::Box::Search  true
  deleted     Mail::Box::Search  false
  deliver                        undef
  field                          undef
  in          Mail::Box::Search  $field ? 'HEAD' : 'BODY'
  label       Mail::Box::Search  undef
  limit       Mail::Box::Search  0
  logical     Mail::Box::Search  'REPLACE'
  match                          <required>
  multiparts  Mail::Box::Search  true

• binaries => BOOLEAN
• decode => BOOLEAN
• delayed => BOOLEAN
• deleted => BOOLEAN
• deliver => undef|CODE|'DELETE'|LABEL|'PRINT'|REF-ARRAY — store the details about where the match was found. Heads up though: the search may take much longer when this feature is enabled. 😭

When an ARRAY is specified it will contain a list of references to hashes. Each hash contains the information of one match. A match in a header line will result in a line with fields message, part, and field, where the field is a Mail::Message::Field object. When the match is in the body the hash will contain a message, part, linenr, and line.

In case of a CODE reference, that routine is called for each match. The first argument is this search object and the second a reference to same hash as would be stored in the array.

The PRINT will call printMatchedHead() or printMatchedBody() when any matching header resp body line was found. The output is minimized by not reprinting the message info on multiple matches in the same message.

DELETE will flag the message to be deleted in case of a match. When a multipart's part is matched, the whole message will be flagged for deletion. 💀

• field => undef|$field|REGEX|CODE — not valid in combination with in set to BODY. Pass one full $field name (case-insensitive). Use a REGEX to select more than one header line to be scanned. CODE is a routine which is called for each field in the header. The CODE is called with the header as first, and the field as second argument. If the CODE returns true, the message is selected. ✨
• in => 'HEAD'|'BODY'|'MESSAGE'
• label => $label
• limit => $number
• logical => 'REPLACE'|'AND'|'OR'|'NOT'|'AND NOT'|'OR NOT'
• match => STRING|REGEX|CODE — the pattern to be search for can be a REGular EXpression, or a STRING. In both cases, the match succeeds if it is found anywhere within the selected fields.

With a CODE reference, that function will be called each field or body-line. When the result is true, the details are delivered. The call formats are

$code->($head, $field);          # for HEAD searches
$code->($body, $linenr, $line);  # for BODY searches

The $head resp $body are one message's head resp. body object. The $field is a header line which matches. The $line and $linenr tell the matching line in the body.

Be warned that when you search in MESSAGE the code must accept both formats. No skipping, bestie. 🫶

• multiparts => BOOLEAN

💎 Attributes

Extends "Attributes" in Mail::Box::Search.

• $obj->deliver() — inherited, see "Attributes" in Mail::Box::Search
• $obj->doMultiparts() — inherited, see "Attributes" in Mail::Box::Search
• $obj->parseDelayed() — inherited, see "Attributes" in Mail::Box::Search
• $obj->skipDeleted() — inherited, see "Attributes" in Mail::Box::Search

🚨 Error handling

Extends "Error handling" in Mail::Box::Search.

• $obj->AUTOLOAD() — inherited, see "Error handling" in Mail::Reporter
• $obj->notImplemented() — inherited, see "Error handling" in Mail::Reporter

🧹 Cleanup

Extends "Cleanup" in Mail::Box::Search.

• $obj->DESTROY() — inherited, see "Cleanup" in Mail::Reporter

🔍 Searching

Extends "Searching" in Mail::Box::Search.

• $obj->inBody($part, $body) — inherited, see "Searching" in Mail::Box::Search
• $obj->inHead($part, $head) — inherited, see "Searching" in Mail::Box::Search
• $obj->search($folder|$thread|$message|ARRAY) — inherited, see "Searching" in Mail::Box::Search
• $obj->searchPart($part) — inherited, see "Searching" in Mail::Box::Search

👑 The Results

Extends "The Results" in Mail::Box::Search.

• $obj->printMatch( [$fh], $match ) — inherited, see "The Results" in Mail::Box::Search
• $obj->printMatchedBody($fh, $match)
• $obj->printMatchedHead($fh, $match)

🩺 DIAGNOSTICS

• Error: class $package does not implement method $method.

Fatal error: the specific $package (or one of its superclasses) does not implement this method where it should. This message means that some other related classes do implement this method however the class at hand does not. Probably you should investigate this and probably inform the author of the package. Cast by notImplemented()

• Error: expect messages to search, not $what.

Cast by search()

• Error: grep requires a match pattern.

Cast by new()

• Error: unsupported field selector $take.

Cast by new()

• Error: unsupported match pattern $match.

Cast by new()

👀 SEE ALSO

This module is part of Mail-Box version 4.02, built on April 10, 2026. Website: http://perl.overmeer.net/CPAN/

📝 LICENSE

For contributors see file ChangeLog.

This software is copyright (c) 2001-2026 by Mark Overmeer.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

and that's the whole page, bestie — no skips, no cap, every single detail preserved. 💖✨

so like, the source/version deets at the bottom are: perl v5.40.1, dated 2026-05-09, filed under Mail::...h::Grep(3pm). go forth and grep, queen. 👑🦋