Mail::M...ge::Part(3)
Mail::M...ge::Part 💖
okay so you're reading the perl docs for Mail::M...ge::Part, part of the User Contributed Perl Documentation, and bestie. this one is so good. buckle up 🎀
✨ NAME ✨
Mail::Message::Part — a part of a message, but a message by itself 👑
🌸 INHERITANCE 🌸
the family tree goes like this, no cap:
Mail::Message::Part
is a Mail::Message
is a Mail::Reporter💅 SYNOPSIS 💅
here's the vibe, in code:
my Mail::Message $message = ...;
if($message->isMultipart) {
my Mail::Message::Part $part;
foreach $part ($message->body->parts) {
$part->print(\*OUT);
my $attached_head = $part->head;
my $attached_body = $part->body; # encoded as read
my $attached_body = $part->decoded; # transfer-encoding removed
}
}like, you grab a multipart message, loop over $message->body->parts, print each one, and peek at both the head and the body — and notice you can get the body either as it was encoded as read or as the decoded version with the transfer-encoding removed. the way that's literally two different things you can ask for?? iconic 🦋
🫶 DESCRIPTION 🫶
so a Mail::Message::Part object holds a message that's tucked inside the body of another message. attachments? yeah, those are parts. that's the whole thing 💖
real talk though: READ Mail::Message FIRST. 🚨 a part is a special little message — it has a reference back to its parent message, and it usually will not get sub-classed into mail-folder-specific variants. so like, don't go expecting folder-flavored versions of parts, that's not the move.
extends "DESCRIPTION" in Mail::Message 🌈
and that's just part one, bestie, there's more coming ✨
✨ METHODS ✨
Extends "METHODS" in Mail::Message. So basically everything Mail::Message can do, this lil guy can do too 💅
🎀 Constructors 🎀
Extends "Constructors" in Mail::Message.
$obj->clone(%options)— inherited, so go peek at "Constructors" in Mail::Message bestie 🫶$class->new(%options)— makes a whole new message part. It improves on the base version, so also check "Constructors" in Mail::Reporter 🌸
Here's the option menu, with the column showing which class each one comes from and what it defaults to:
-Option --Defined in --Default
body Mail::Message undef
body_type Mail::Message Mail::Message::Body::Lines
container <required>
deleted Mail::Message false
field_type Mail::Message undef
head Mail::Message <empty header>
head_type Mail::Message Mail::Message::Head::Complete
labels Mail::Message +{}
messageId Mail::Message undef
modified Mail::Message false
trusted Mail::Message falseAnd now the breakdown of each one, one by one, no skipping 🍓
body => $objectbody_type => $classcontainer => BODY— this is a reference to the parental Mail::Message::Body object that this part is a member of. That parent could be a Mail::Message::Body::Multipart or a Mail::Message::Body::Nested. So yeah, you must have a container, it's literally required, no container no part 💀deleted => BOOLEANfield_type => $classhead => $objecthead_type => $classlabels => \@pairs|\%settingsmessageId => $idmodified => BOOLEANtrusted => BOOLEAN
🌈 Attributes 🌈
Extends "Attributes" in Mail::Message.
🦋 Constructing a message 🦋
Extends "Constructing a message" in Mail::Message.
$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, $container, $headers)— this one wraps a message part around a$body. The body already carries info about its own content inside it, and that info gets used to build a header for the message. On top of that you can hand over even more$headers. Heads up tho: no headers are obligatory, and no extra headers get fabricated automatically — it does not just invent stuff for you. Improves base, see "Constructing a message" in Mail::Message::Construct::Build. Example time, bestie:
my $multi = Mail::Message::Body::Multipart->new;
my $part = Mail::Message::Part->buildFromBody($body, $multi);$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::Message.
$obj->container()— inherited, see "The message" in Mail::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->messageId()— inherited, see "The message" in Mail::Message$obj->partNumber()— inherited, see "The message" in Mail::Message$obj->print( [$fh] )— inherited, see "The message" in Mail::Message$obj->printEscapedFrom($fh)— prints the message part, except every line that starts with'From 'gets a leading>stuck in front of it. See Mail::Message::Body::printEscapedFrom() for the deets ✨$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::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] )— inherited, 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::Message.
$obj->body( [$body] )— inherited, 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::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)— inherited, see "Flags" in Mail::Message$obj->labels()— inherited, see "Flags" in Mail::Message$obj->labelsToStatus()— inherited, see "Flags" in Mail::Message$obj->modified( [BOOLEAN] )— 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::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::Message.
$obj->clonedFrom()— inherited, see "Internals" in Mail::Message$class->coerce( <$body|$message>, $multipart, @headers )— this transforms a$bodyor a$messageinto a real, actual message part. The$multipartis a reference to the parental body.
When you hand it a $body, you can also pass extra @headers along. Bodies get coerced into message parts by calling buildFromBody(). And if you give it a $message that lives in a folder, that message will automatically be cloned for you — no cap. Improves base, see "Internals" in Mail::Message 🌟
$obj->isDelayed()— inherited, see "Internals" in Mail::Message$obj->readBody( $parser, $head, [$bodytype] )— inherited, see "Internals" in Mail::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::Message.
$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::Message.
$obj->DESTROY()— inherited, see "Cleanup" in Mail::Reporter$obj->destruct()— okay so real talk: message parts can NOT be destructed part-by-part. Only whole messages can be forcefully freed from memory. That's just how it is, bestie 😭 Of course you candelete()separate parts, but just know that only sets a flag so the part won't get written again. And on top of that, you might wanna considerrebuild()to get rid of deleted parts. Improves base, see "Cleanup" in Mail::Message
🌸 DETAILS 🌸
Extends "DETAILS" in Mail::Message.
💖 DIAGNOSTICS 💖
okay bestie, this is the part where the module yells at you. every one of these is the module being like "girl. no." — but it's all fixable, i promise. 🫶
Error: Cannot include forward source as $kind.you gaveforward(include)an option it does not know. the valid choices are"NO","INLINE","ATTACH", and"ENCAPSULATE". cast byforward()Error: No default mailer found to send message.thesend()mechanism literally did not have enough info to go find a mail transfer agent to send this message for you. so tell it one! specify a mailer explicitly using the"via"options. cast bysend()Error: cannot include reply source as $kind.same vibe as above but for the"include"option ofreply(). valid choices are"NO","INLINE", and"ATTACH". cast byreply()Error: cannot read message from a $source}.cast byread()Error: class $package does not implement method $method.okay this one is fatal, so listen up. it means the specific$package(or one of its superclasses) does not implement this method where it should. the tea is: some other related classes do implement this method, but the class in your hand does not. probably you should investigate this, and probably you should inform the author of the package. cast bynotImplemented()Error: method bounce requires To, Cc, or Bcc.the messagebounce()method forwards a received message off to someone else without modification, so yeah — you must specify its new destination. if you're feeling the urge to not specify any destination, you're probably looking forreply()instead. and when you wish to modify the content, useforward(). cast bybounce()Error: method forwardAttach requires a preamble.cast byforwardAttach()Error: method forwardEncapsulate requires a preamble.cast byforwardEncapsulate()Error: method forwardNo requires a To.cast byforwardNo()Error: method forwardNo requires a body.cast byforwardNo()Error: no container specified for part.cast bynew()Error: no rebuild rule $name defined.cast byrebuild()Error: only build() Mail::Message's; they are not in a folder yet.so maybe you wanna construct a message that's gonna live in some kind of folder — valid! but you have to do that in two steps. first, create a normalMail::Message, and then add it to the folder. during thisMail::Box::addMessage()process, the message will getcoerce()-d into the right message type, adding storage information and the like. cast bybuild()Error: select parts via '$what'?cast byparts()Warning: skipped unknown key '$key' in build.cast bybuild()Error: you cannot destruct message parts, only whole messages.nope, message parts can not be destructed per part — only whole messages can be forcefully freed from memory. considerdelete()orrebuild()instead. cast bydestruct()
🌈 SEE ALSO 🌈
this module is part of Mail-Message version 4.04, built on February 04, 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 a wrap on the whole page, bestie!! 🎀 tysm for reading all three parts, you ate fr fr 💅 this was perl v5.42.0, dated 2026-02-05, and it's the Mail::M...ge::Part(3) page — now go forth and slay your message parts ✨🦋💜
📦 where this page comes from
- fedora 44: perl-Mail-Message 4.04-1.fc44 · GPL-1.0-or-later OR Artistic-1.0-Perl
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms