Mail::...ructed(3pm)

📦

version 4.02 · 9 versions

💖 Mail::Box::Message::Destructed — the manual, bestie edition 💖

okay so this is Mail::Box::Message::Destructed(3pm) from the User Contributed Perl Documentation section, and it's literally about ✨destructed messages✨. yes that's a real word. sit down, we're doing this 🫶

✨ NAME ✨

Mail::Box::Message::Destructed — a destructed message 🩹

🌸 INHERITANCE 🌸

the family tree goes like this, no cap:

Mail::Box::Message::Destructed
  is a Mail::Box::Message
  is a Mail::Message
  is a Mail::Reporter

so she's a Mail::Box::Message, which is a Mail::Message, which is a Mail::Reporter. generational icon behavior honestly 👑

🎀 SYNOPSIS 🎀

one line. that's it. that's the whole vibe:

$folder->message(3)->destruct;

call destruct on message 3 of your folder and boom, she's gone 💀

🦋 DESCRIPTION 🦋

okay so picture this: when a message folder gets read, every single message gets parsed into Perl structures. and the header structure specifically? she can eat a HUGE amount of memory. like, alarming amounts. (the message bodies can get moved out to external temporary files, so at least those are chill, but the headers stay.)

so destructed messages are what happens when you forcefully clean up all the header AND body info. everything gets wiped, which makes the object much smaller. some useful information is still hanging around in the object though — she's not completely empty, bestie, just... minimalist 💅

⚠️ BE WARNED, FR FR: once a message is destructed, it cannot be revived. like, at all. no takebacks, no undo, no "wait actually—". it's giving irreversible.

and it's not just the object that's affected — destructing enforces irreversable deletion from the folder. so if you've got a folder opened read-only, the message will stay in that folder (phew 🫶). but otherwise it may be deleted. so. yeah. know what you're doing before you do it 😭

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

more parts coming, don't go anywhere 💜

💅 METHODS 💅

Extends "METHODS" in Mail::Box::Message. Yeah bestie, we're building on top of that one, keep up 💖

🎀 Constructors 🎀

Extends "Constructors" in Mail::Box::Message. More inheritance, we love to see it.

$obj->clone(%options) — inherited, so go read "Constructors" in Mail::Message, it's all there 🫶
$class->new($msgid, %options) — okay so heads up: you literally cannot make a destructed message object. Like, at all. That's the whole point of it. The destructing happens over in Mail::Box::Message::destruct(). This one improves the base, so peek at "Constructors" in Mail::Reporter for the deets.

So here's the option rundown — every single one, no skips 💀

body — from Mail::Message, defaults to undef
body_type — from Mail::Box::Message, defaults to <from folder>
deleted — from Mail::Message, defaults to false
field_type — from Mail::Message, defaults to undef
folder — from Mail::Box::Message, defaults to <required> (yes bb it's mandatory)
head — from Mail::Message, defaults to undef
head_type — from Mail::Message, defaults to Mail::Message::Head::Complete
labels — from Mail::Message, defaults to +{}
messageId — from Mail::Message, defaults to undef
message_id — from Mail::Message, defaults to undef
modified — from Mail::Message, defaults to false
size — from Mail::Box::Message, defaults to undef
trusted — from Mail::Message, defaults to false

And now what each one actually means ✨

body => $object — the body, as an object
body_type => CODE|$class — what kind of body you want
deleted => BOOLEAN — is it deleted or not, true/false vibe
field_type => $class — class used for fields
folder => $folder — the folder it lives in
head => $object — the head, as an object
head_type => $class — class used for the head
labels => \@pairs|\%settings — labels, either as pairs or as a hash
messageId => $id — the message id
message_id => $id — also the message id (two ways to spell it, be nice)
modified => BOOLEAN — has it been modified, true/false
size => $bytes — size in bytes
trusted => BOOLEAN — trusted or not, true/false

🦋 Attributes 🦋

Extends "Attributes" in Mail::Box::Message. Look at us, still extending things.

$obj->bodyType() — inherited, check "Attributes" in Mail::Message
$obj->fieldType() — inherited, check "Attributes" in Mail::Message
$obj->folder( [$folder] ) — inherited, check "Attributes" in Mail::Box::Message
$obj->headType() — inherited, check "Attributes" in Mail::Message
$obj->messageId() — inherited, check "Attributes" in Mail::Message
$obj->seqnr( [$integer] ) — inherited, check "Attributes" in Mail::Box::Message

🌸 Constructing a message 🌸

Extends "Constructing a message" in Mail::Box::Message. So many inherited methods, it's giving family reunion 🫶

$obj->bounce( [<$rg_object|%options>] ) — inherited, see "Constructing a message" in Mail::Message::Construct::Bounce
$class->build( [$message|$part|$body], @fields, %options ) — inherited, see "Constructing a message" in Mail::Message::Construct::Build
$class->buildFromBody($body, [$head], $headers) — inherited, see "Constructing a message" in Mail::Message::Construct::Build
$obj->forward(%options) — inherited, see "Constructing a message" in Mail::Message::Construct::Forward
$obj->forwardAttach(%options) — inherited, see "Constructing a message" in Mail::Message::Construct::Forward
$obj->forwardEncapsulate(%options) — inherited, see "Constructing a message" in Mail::Message::Construct::Forward
$obj->forwardInline(%options) — inherited, see "Constructing a message" in Mail::Message::Construct::Forward
$obj->forwardNo(%options) — inherited, see "Constructing a message" in Mail::Message::Construct::Forward
$obj->forwardPostlude() — inherited, see "Constructing a message" in Mail::Message::Construct::Forward
$obj->forwardPrelude() — inherited, see "Constructing a message" in Mail::Message::Construct::Forward
$obj->forwardSubject(STRING) — inherited, see "Constructing a message" in Mail::Message::Construct::Forward
$class->read($fh|$text|\$text|\@lines, %options) — inherited, see "Constructing a message" in Mail::Message::Construct::Read
$obj->rebuild(%options) — inherited, see "Constructing a message" in Mail::Message::Construct::Rebuild
$obj->reply(%options) — inherited, see "Constructing a message" in Mail::Message::Construct::Reply
$obj->replyPrelude( [STRING|$field|$address|\@addrs|\@fields] ) — inherited, see "Constructing a message" in Mail::Message::Construct::Reply
$any->replySubject(STRING) — inherited, see "Constructing a message" in Mail::Message::Construct::Reply

👑 The message 👑

Extends "The message" in Mail::Box::Message. Main character energy, honestly.

$obj->container() — inherited, see "The message" in Mail::Message
$obj->copyTo($folder, %options) — inherited, see "The message" in Mail::Box::Message
$obj->endsOnNewline() — inherited, see "The message" in Mail::Message
$obj->isDummy() — inherited, see "The message" in Mail::Message
$obj->isPart() — inherited, see "The message" in Mail::Message
$obj->moveTo($folder, %options) — inherited, see "The message" in Mail::Box::Message
$obj->partNumber() — inherited, see "The message" in Mail::Message
$obj->print( [$fh] ) — inherited, see "The message" in Mail::Message
$obj->send( [$mailer], %options ) — inherited, see "The message" in Mail::Message
$obj->size() — inherited, see "The message" in Mail::Message
$obj->toplevel() — inherited, see "The message" in Mail::Message
$obj->write( [$fh] ) — inherited, see "The message" in Mail::Message

✨ The header ✨

Extends "The header" in Mail::Box::Message.

$obj->bcc() — inherited, see "The header" in Mail::Message
$obj->cc() — inherited, see "The header" in Mail::Message
$obj->date() — inherited, see "The header" in Mail::Message
$obj->destinations() — inherited, see "The header" in Mail::Message
$obj->from() — inherited, see "The header" in Mail::Message
$obj->get($fieldname) — inherited, see "The header" in Mail::Message
$obj->guessTimestamp() — inherited, see "The header" in Mail::Message
$obj->head( [$head] ) — okay so when undef gets passed in as $head, nothing changes at all, it just returns silently, no drama 🫶 But in every other case, this method is gonna start complaining that the header has been removed. Improves the base, see "The header" in Mail::Message
$obj->nrLines() — inherited, see "The header" in Mail::Message
$obj->sender() — inherited, see "The header" in Mail::Message
$obj->study($fieldname) — inherited, see "The header" in Mail::Message
$obj->subject() — inherited, see "The header" in Mail::Message
$obj->timestamp() — inherited, see "The header" in Mail::Message
$obj->to() — inherited, see "The header" in Mail::Message

💜 The body 💜

Extends "The body" in Mail::Box::Message.

$obj->body( [$body] ) — same deal as the header one, bestie: pass undef as $body and literally nothing happens, it just returns quietly 💅 Any other case, it will complain that the body data has been removed. Improves the base, see "The body" in Mail::Message
$obj->contentType() — inherited, see "The body" in Mail::Message
$obj->decoded(%options) — inherited, see "The body" in Mail::Message
$obj->encode(%options) — inherited, see "The body" in Mail::Message
$obj->isMultipart() — inherited, see "The body" in Mail::Message
$obj->isNested() — inherited, see "The body" in Mail::Message
$obj->parts( [<'ALL'|'ACTIVE'|'DELETED'|'RECURSE'|$filter>] ) — inherited, see "The body" in Mail::Message

🍓 Flags 🍓

Extends "Flags" in Mail::Box::Message.

$obj->delete() — inherited, see "Flags" in Mail::Message
$obj->deleted( [BOOLEAN] ) — inherited, see "Flags" in Mail::Message
$obj->isDeleted() — inherited, see "Flags" in Mail::Message
$obj->isModified() — inherited, see "Flags" in Mail::Message
$obj->label($label|PAIRS) — so yeah, you can delete a destructed message, no problem. But you cannot undelete it. That's just how it is. Improves the base, see "Flags" in Mail::Message
$obj->labels() — inherited, see "Flags" in Mail::Message
$obj->labelsToStatus() — inherited, see "Flags" in Mail::Message
$obj->modified( [$flag] ) — inherited, see "Flags" in Mail::Message
$obj->statusToLabels() — inherited, see "Flags" in Mail::Message

🌈 The whole message as text 🌈

Extends "The whole message as text" in Mail::Box::Message.

$obj->file() — inherited, see "The whole message as text" in Mail::Message::Construct::Text
$obj->lines() — inherited, see "The whole message as text" in Mail::Message::Construct::Text
$obj->printStructure( [$fh|undef],[$indent] ) — inherited, see "The whole message as text" in Mail::Message::Construct::Text
$obj->string() — inherited, see "The whole message as text" in Mail::Message::Construct::Text

💀 Internals 💀

Extends "Internals" in Mail::Box::Message. Down bad in the guts of it all 🔥

$obj->clonedFrom() — inherited, see "Internals" in Mail::Message
$class->coerce($message) — coerces a Mail::Box::Message into destruction 😭 Improves the base, see "Internals" in Mail::Message

Example of coercion to death:

Mail::Box::Message::Destructed->coerce($folder->message(1));
$folder->message(1)->destruct;  # same

my $msg = $folder->message(1);
Mail::Box::Message::Destructed->coerce($msg);
$msg->destruct;                 # same

$obj->diskDelete() — inherited, see "Internals" in Mail::Box::Message
$obj->isDelayed() — inherited, see "Internals" in Mail::Message
$obj->isTrusted() — inherited, see "Internals" in Mail::Message
$obj->readBody( $parser, $head, [$bodytype] ) — inherited, see "Internals" in Mail::Box::Message
$obj->readFromParser( $parser, [$bodytype] ) — inherited, see "Internals" in Mail::Message
$obj->readHead( $parser, [$class] ) — inherited, see "Internals" in Mail::Message
$obj->recursiveRebuildPart($part, %options) — inherited, see "Internals" in Mail::Message::Construct::Rebuild
$obj->storeBody($body) — inherited, see "Internals" in Mail::Message
$obj->takeMessageId( [STRING] ) — inherited, see "Internals" in Mail::Message

😭 Error handling 😭

Extends "Error handling" in Mail::Box::Message. It's giving damage control, and honestly? Fair.

$obj->AUTOLOAD() — inherited, see "METHODS" in Mail::Message::Construct
$obj->notImplemented() — inherited, see "Error handling" in Mail::Reporter
$any->shortSize( [$value] ) — inherited, see "Error handling" in Mail::Message
$obj->shortString() — inherited, see "Error handling" in Mail::Message

🧚 Cleanup 🧚

Extends "Cleanup" in Mail::Box::Message. Time to go, besties 👋

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

⭐ DETAILS ⭐

Extends "DETAILS" in Mail::Box::Message. Yeah, that's it. Go read that one, iykyk 💖

💀 DIAGNOSTICS 💀

okay bestie, this is the part where Perl yells at you. Every one of these is a real message your code can trip over, and yes, each one tells you which method cast it, so you know exactly who to blame. iykyk. 🔥

Error: Cannot include forward source as $kind. — you handed forward(include) an alternative it doesn't know. the valid choices are "NO", "INLINE", "ATTACH", and "ENCAPSULATE". Cast by forward().
Error: No default mailer found to send message. — the send() mechanism didn't have enough info to automatically hunt down a mail transfer agent to send this message with. tell it a mailer explicitly using the "via" options. Cast by send().
Error: You cannot take the head/body of a destructed message — the message came from a folder, but its memory got freed-up forcefully by Mail::Box::Message::destruct(). apparently your program is still trying to reach the header or body data after that destruction, which honestly? not possible. Cast by head().
Error: cannot include reply source as $kind. — unknown alternative for the "include" option of reply(). valid choices are "NO", "INLINE", and "ATTACH". Cast by reply().
Error: cannot read message from a $source. — Cast by read().
Error: class $package does not implement method $method. — fatal error bestie: that specific $package (or one of its superclasses) does not implement this method where it should. what it actually means is that some other related classes do implement this method, but the class you're holding does not. you should probably investigate this, and probably go tell the author of the package. Cast by notImplemented().
Error: destructed message can not be undeleted — once a message is destructed it can not be revived. destruction is an optimization in memory usage: if you need an undelete functionality, then you can not use Mail::Box::Message::destruct(). Cast by label().
Error: destructed message has no labels except 'deleted', requested is $label. — Cast by label().
Error: destructed message has no labels except 'deleted', trying to set @labels. — Cast by label().
Error: method bounce requires To, Cc, or Bcc. — the bounce() method forwards a received message off to someone else without modification, so you must specify its new destination. if you have the urge not to specify any destination, you're probably looking for reply(). when you wish to modify the content, use forward(). Cast by bounce().
Error: method forwardAttach requires a preamble. — Cast by forwardAttach().
Error: method forwardEncapsulate requires a preamble. — Cast by forwardEncapsulate().
Error: method forwardNo requires a To. — Cast by forwardNo().
Error: method forwardNo requires a body. — Cast by forwardNo().
Error: no rebuild rule $name defined. — Cast by rebuild().
Error: only build() Mail::Message's; they are not in a folder yet. — so you wanna construct a message to be stored in some kind of folder, but babes, you need to do that in two steps. first, create a normal Mail::Message, and then add it to the folder. during that Mail::Box::addMessage() process the message will get coerce()-d into the right message type, adding storage information and the like. Cast by build().
Error: select parts via '$what'? — Cast by parts().
Warning: skipped unknown key '$key' in build. — Cast by build().
Error: you cannot coerce a $class into destruction. — only real Mail::Box::Message objects can get destructed into Mail::Box::Message::Destructed objects. Mail::Message free their memory immediately when the last reference is lost. Cast by coerce().
Error: you cannot instantiate a destructed message. — you cannot instantiate a destructed message object directly, no cap. destruction is done by calling Mail::Box::Message::destruct() on any existing folder message. Cast by new().
Error: you cannot set the body on a destructed message. — Cast by body().
Error: you cannot set the head on a destructed message. — Cast by head().
Error: you cannot set the modified flag on a destructed message. — Cast by modified().
Error: you cannot take the body of a destructed message. — Cast by body().
Error: you cannot take the head of a destructed message. — Cast by head().

🌈 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 is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. periodt. 💅

okay that's the whole page, bestie, you made it to the end and you ate 🫶 this was Mail::...ructed(3pm), running on perl v5.40.1, dated 2026-05-09 — go forth and destruct responsibly 🎀💖

📦 where this page comes from

ubuntu stonking: libmail-box-perl 4.02-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms