Mail::...:Search(3pm)

📦
version 4.02 · 9 versions
, in ubuntu stonking

💖 Mail::Box::Search — the manual page, but make it a group chat 💖

okay bestie, so this is Mail::Box::Search(3pm), from the User Contributed Perl Documentation section of your man pages. She's the queen bee base class of message-searching, and she's about to explain herself. pull up a chair 🫶

✨ NAME ✨

Mail::Box::Search — select messages within a mail box 🎀

🌸 INHERITANCE 🌸

the family tree, no cap:

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

Mail::Box::Search is extended by
  Mail::Box::Search::Grep
  Mail::Server::IMAP4::Search

🦋 SYNOPSIS 🦋

the whole vibe in like six lines, obsessed:

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

my $filter = Mail::Box::Search::[something]->new;
my @msgs   = $filter->search($folder, ...);
if($filter->search($message)) {...}

💅 DESCRIPTION 💅

so this Mail::Box::Search class is literally the base class for a whole little crew of message-scanning algorithms. the messages that get picked can be labeled, and yes, boolean operations on messages are supported. it's giving powerful.

currently implemented searches:

  • Mail::Box::Search::Grep — matches a header or a body against a regular expression, in a UNIX grep-ish kind of way. iconic behavior.
  • Mail::Box::Search::SpamAssassin — RIP babe 😭 the original implementation only supported SpamAssassin 2.x, so this one got removed for Mail::Box 4. gone but not forgotten.
  • Mail::Box::Search::IMAP — searches an IMAP folder using the special interface that IMAP folders provide for it. heads up tho: the implementation is not completed.

also, this extends "DESCRIPTION" in Mail::Reporter. 💜

⭐ METHODS ⭐

extends "METHODS" in Mail::Reporter, meaning the base class already brought snacks. now for the extras:

🧚 Constructors

extends "Constructors" in Mail::Reporter.

$class->new(%options)

creates a filter. it improves on the base one, so go peek at "Constructors" in Mail::Reporter if you want the lore.

 -Option    --Default
  binaries    <C<false>>
  decode      <C<true>>
  delayed     true
  deleted     false
  deliver     undef
  in          'BODY'
  label       undef
  limit       0
  logical     'REPLACE'
  multiparts  true

here's the tea on every single one, don't skip:

  • binaries => BOOLEAN — do we let binary bodies into the search or not? that's the whole question.
  • decode => BOOLEAN — decode the messages before the search happens. because even plain text messages can be encoded, for instance as "quoted-printable", and that can absolutely mess with your results. but watch out: decoding will slow the search down. trade-offs, bestie 💀
  • delayed => BOOLEAN — include the delayed messages (which will be parsed) in the search. if you set this to "false", you may find fewer hits, so don't come crying later.
  • deleted => BOOLEAN — in most cases you're not gonna care about results found in messages that are flagged to be deleted. but with this option you can say actually yes, search those too.
  • deliver => undef|CODE|'DELETE' — the exact functionality of this parameter differs per search method, so read the applicable man-page, bestie, fr fr. in any case "undef" means details are not collected for this search, which is the fastest search. "DELETE" will flag the message to be flagged for deletion. you may also specify your own CODE reference. with a reference to an array, the information about the matches is collected as a list of hashes, one hash per match. 👑
  • in => 'HEAD'|'BODY'|'MESSAGE' — where to look for the match. that's it, that's the whole option.
  • label => $label — mark all selected messages with the specified label. if this field is not specified, the message will not get a label; search() also returns a LIST of selected messages.
  • limit => $number — limit the search to the specified $number of messages. when the $number is positive, the search starts at the first message in the folder or thread. a negative $number starts at the end of the folder. if the limit is set to zero, there is no limit. periodt.
  • logical => 'REPLACE'|'AND'|'OR'|'NOT'|'AND NOT'|'OR NOT' — only applicable in combination with a "label". this is about how to handle the labels that are already there:
    • "REPLACE" — messages which already carry the label get stripped from their selection (unless they match again).
    • "AND" — the message must be selected by this search and already carry the label, otherwise the label will not be set.
    • "OR" — newly selected messages get added to the set of already selected messages.
    • "NOT" is "true" for messages which do not fulfil the search. the details output will still contain the places where the match was found, however those messages — the complementary set of messages — will be labeled and returned. sneaky but valid. 🙈
  • multiparts => BOOLEAN — are multiparts included in the search results or not? some MUA have problems handling details received from the search. when this flag is turned off, the body of multiparts will be ignored. the parts search will include the preamble and epilogue.

🌈 Attributes

extends "Attributes" in Mail::Reporter.

  • $obj->deliver()
  • $obj->doMultiparts()
  • $obj->parseDelayed()
  • $obj->skipDeleted()

🎀 Error handling

extends "Error handling" in Mail::Reporter.

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

🫶 Cleanup

extends "Cleanup" in Mail::Reporter.

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

🔥 Searching

  • $obj->inBody($part, $body) — tests whether the body contains the requesting information. see the specific search module for its parameters.
  • $obj->inHead($part, $head) — tests whether the header contains the requesting information. see the specific search module for its parameters. (same energy, different body part, iykyk)
  • $obj->search($folder|$thread|$message|ARRAY) — checks which messages from the $folder (Mail::Box) match the search parameters. the matched messages are returned as a list. you can also specify a $thread (a Mail::Box::Thread::Node), one single $message (a Mail::Message), or an "ARRAY" of messages.

sometimes we know how only one match is needed. in this case, this searching will stop at the first match. for instance, when "limit" is -1 or 1, or when the search is done in scalar context.

example, because we love a demonstration:

my $grep = Mail::Box::Search::Grep->new(
  match   => 'My Name Is Nobody',
  deliver => 'PRINT'
);

$grep->search($folder);

my $message = $folder->message(3);
$grep->search($message);

my $thread  = $message->threadStart;
$grep->search($thread);
  • $obj->searchPart($part) — search this message $part for matches.

💜 The Results

  • $obj->printMatch( [$fh], HASH ) — print the information about the match (see new(deliver)) in some understandable way. if no file handle $fh is specified, the output will go to the selected filehandle (see "perldoc -f select").

😭 DIAGNOSTICS 😭

the "something went wrong" corner. read these, they're not decorative:

  • Error: cannot search in body. — the search object does not implement inBody(), and can therefore not search a message body. cast by new()
  • Error: cannot search in header. — the search object does not implement inHead(), and can therefore not search a message header. cast by new()
  • 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: don't know how to deliver results in $what. — the search results cannot be delivered in the specific way, because that is not a defined alternative. cast by new()
  • Error: expect messages to search, not $what. — cast by search()
  • Error: search in BODY, HEAD or MESSAGE, not $what. — the "in" option offers only three alternatives. 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 💖 go search some mailboxes, you're gonna slay.

that was perl v5.40.1, dated 2026-05-09 — mwah, talk later 🦋✨

📦 where this page comes from