Mail::...::HASH(3pm)

💖 NAME 💖

okay bestie, meet Mail::Box::Tie::HASH — it lets you access an existing message folder as a hash. like, a whole folder, but you poke at it with %hash syntax. iconic behavior fr fr 👑

(the manual page is filed under Mail::...::HASH(3pm) if you're out here hunting for it, mwah 💅)

---

🌈 INHERITANCE 🌈

Mail::Box::Tie::HASH
  is a Mail::Box::Tie

so it's a child of Mail::Box::Tie, it inherited the family lewks, no cap.

---

✨ SYNOPSIS ✨

tie my(%inbox), 'Mail::Box::Tie::HASH', $folder;

foreach my $msgid (keys %inbox)
{   print $inbox{$msgid};
    delete $inbox{$msgid};
}

$inbox{$msg->messageId} = $msg;

like literally three moves and you've got a whole mailbox as a hash. the way that just works 🦋

---

🎀 DESCRIPTION 🎀

ngl, when you look at a folder as being a set of related messages based on message-id, it is so logical to access the folder through a hash. big brain move, we're obsessed 💖

for a tied hash, the message-id is used as the key. the message-id is usually unique, BUT — and this is the tea — when two or more instances of the same message are in the same folder, one will be flagged for deletion and the other will be returned. so like, one of them has to go, sorry babe 💀

this implementation uses basic folder access routines which are related to the message-id. (lowkey that's the whole vibe.)

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

---

🌸 METHODS 🌸

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

🧚 Constructors 🧚

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

• tie %hash, 'Mail::Box::Tie::HASH', FOLDER — connects the FOLDER object to a HASH. it's giving matchmaker, except both of them are the same thing. 🔥

» example:

my $mgr    = Mail::Box::Manager->new;
my $folder = $mgr->open(access => 'rw');
tie my(%inbox), 'Mail::Box::Tie::HASH', $folder;

• $class->new($folder, $type) — inherited, see "Constructors" in Mail::Box::Tie. (not her moment, she's on loan from the parent class, periodt.)

⭐ Attributes ⭐

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

• $obj->folder() — inherited, see "Attributes" in Mail::Box::Tie.
• $obj->type() — inherited, see "Attributes" in Mail::Box::Tie.

👑 Tied Interface 👑

• $obj->CLEAR() — remove the contents of the hash. bestie, this is not really possible, but all the messages will be flagged for deletion. so it's giving "cleared" but it's actually just "marked, we'll deal with it later" 🙈

» example:

%inbox = ();
%inbox = ($msg->messageId, $msg); #before adding msg

• $obj->DELETE($message_id) — remove the message with the specified $message_id. bye boo 💅

» example:

delete $inbox{$msgid};

• $obj->EXISTS($message_id) — check whether a message with a certain $message_id exists. vibe check: does it exist or not ✨

» example:

if(exists $inbox{$msgid}) ...

• $obj->FETCH($message_id) — get the message with the specified id. heads up: the returned message may be a dummy if message thread detection is used. and it returns undef when there is no message with the specified id. no message, no service 😭

» example:

my $msg = $inbox{$msgid};
if($inbox{$msgid}->isDummy)  ...

• $obj->FIRSTKEY() — see NEXTKEY(). (she's the opening act, NEXTKEY is the main character.)
• $obj->NEXTKEY($previous) — FIRSTKEY() returns the first message-id/message pair from the folder, and NEXTKEY returns the message-id/message pair for the next message, in the order in which the message is stored in the folder.

messages flagged for deletion will not be returned. see the Mail::Box::messages() method of the folder type for more information about the folder message order. 👀

» example:

foreach my $msgid (keys %inbox) ...
foreach my $msg (values %inbox) ...

while(my ($msgid, $msg) = each %inbox) {
   $msg->print unless $msg->isDeleted;
}

• $obj->STORE(undef, $message) — store a message in the folder. the key must be undef, because the message-id of the specified message is taken. this is shown in the first example. however, as you see, it is a bit complicated to specify undef, therefore the string "undef" is accepted as well. two ways to say nothing, slay 🫶

the message may be converted into something which can be stored in the folder type which is at stake. the added instance is returned. 🔥

» example:

$inbox{ (undef) } = $msg;
$inbox{undef} = $msg;

---

💀 DIAGNOSTICS 💀

• Error: no folder specified to tie to. — cast by new(). babe you forgot the folder, the whole thing cannot function without a folder 😭
• Warning: use undef as key, because the message-id of the message is used. — cast by STORE(). just use undef, bestie, she's asking nicely 🙈

---

🔥 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. (iykyk 📝)

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. periodt 💖

---

and that's the whole page, bestie 🎀 — signed off from perl v5.40.1, dated 2026-05-09, filed as Mail::...::HASH(3pm). go forth and tie responsibly 💅✨