Mail::M...ltipart(3)

📦
version 4.04 · 11 versions
, in fedora 44

Mail::Message::Body::Multipart(3) 💌

okay so bestie, we're doing the Mail::Message::Body::Multipart manual page, and it's a whole situation — it's long, so this is part 1 of 2. buckle up 🎀

✨ NAME ✨

Mail::Message::Body::Multipart — the body of a message when it's got attachments, aka the part where your email is secretly a whole little zip file of vibes 🦋

🌸 INHERITANCE 🌸

 Mail::Message::Body::Multipart
   is a Mail::Message::Body
   is a Mail::Reporter

   Mail::Message::Body also extends Mail::Reporter
   is a Mail::Reporter

so it's a Mail::Message::Body, which is itself a Mail::Reporter, and Mail::Message::Body also extends Mail::Reporter and is a Mail::Reporter. yes, the family tree loops. it's giving big extended-family-holiday energy, we don't ask questions 💅

🫶 SYNOPSIS 🫶

  See Mail::Message::Body

  if($body->isMultipart) {
     my @attachments = $body->parts;
     my $attachment3 = $body->part(2);
     my $before      = $body->preamble;
     my $after       = $body->epilogue;
     $body->part(1)->delete;
  }

like, first you vibe check it with isMultipart, then you go grab parts, part(2), preamble, epilogue, and if a part is doing too much you just $body->part(1)->delete it. no cap. ✨

💖 DESCRIPTION 💖

The body (content) of a message can be stored in various ways. In this manual-page you find the description of extra functionality you have when a message contains attachments (parts). 📎

The number of multipart alternatives is growing. A full list is maintained by IANA at https://www.iana.org/assignments/media-types/media-types.xhtml#multipart 🔥

  • multipart/mixed
  • multipart/alternative
  • multipart/related
  • multipart/report, RFC6522
  • multipart/signed, RFC1847
  • multipart/encrypted
  • multipart/multilingual, RFC8255 (unused)

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

ngl that last one being marked (unused) is so iconic of it. it's just out here living its truth, unbothered 💀

🌈 OVERLOADED 🌈

Extends "OVERLOADED" in Mail::Message::Body.

  • overload: '""' stringification — inherited, see "OVERLOADED" in Mail::Message::Body
  • overload: '==' numerical comparison — inherited, see "OVERLOADED" in Mail::Message::Body
  • overload: '@{}' addressed as array — inherited, see "OVERLOADED" in Mail::Message::Body
  • overload: bool true/false — inherited, see "OVERLOADED" in Mail::Message::Body

all inherited bestie, this class isn't reinventing the wheel, she's just borrowing it 💅

⭐ METHODS ⭐

Extends "METHODS" in Mail::Message::Body.

🎀 Constructors 🎀

Extends "Constructors" in Mail::Message::Body.

  • $obj->clone() — inherited, see "Constructors" in Mail::Message::Body
  • $class->new(%options) — inherited, see "Constructors" in Mail::Message::Body

here's the whole option menu, defaults and all, no gatekeeping:

 -Option           --Defined in         --Default
  based_on           Mail::Message::Body  undef
  boundary                                undef
  charset            Mail::Message::Body  'PERL'
  checked            Mail::Message::Body  false
  content_id         Mail::Message::Body  undef
  data               Mail::Message::Body  undef
  description        Mail::Message::Body  undef
  disposition        Mail::Message::Body  undef
  eol                Mail::Message::Body  'NATIVE'
  epilogue                                ''
  file               Mail::Message::Body  undef
  filename           Mail::Message::Body  undef
  language           Mail::Message::Body  undef
  message            Mail::Message::Body  undef
  mime_type          Mail::Message::Body  'multipart/mixed'
  modified           Mail::Message::Body  false
  parts                                   undef
  preamble                                undef
  transfer_encoding  Mail::Message::Body  'none'

and now the tea on each one ☕

  • based_on => $body
  • boundary => $separator — the $separator string to be used between parts of the message. This separator must be unique in case the message contains nested multiparts (which are not unusual, lowkey they're everywhere). If undef, a nice unique boundary will be generated for you 🫶
  • charset => $charset|'PERL'|<undef>
  • checked => BOOLEAN
  • content_id => STRING
  • data => @lines|$text
  • description => STRING|$field
  • disposition => STRING|$field
  • eol => 'CR'|'LF'|'CRLF'|'NATIVE'
  • epilogue => $body|$text — the text which is included in the main body after the final boundary. This is usually empty, and has no meaning. 🤷♀️ Provide a $body object or plain $text (which will automatically translated into a text/plain body).
  • file => $file|$handle|$io
  • filename => $file
  • language => STRING|@lang|$field
  • message => $message
  • mime_type => STRING|$field|$mime
  • modified => BOOLEAN
  • parts => [$message, $body, ...] — specifies an initial list of parts in this body. These may be full $message objects, or $body objects which will be transformed into messages before use. Each message is coerced into a Mail::Message::Part object. 💫 MIME::Entity and Mail::Internet objects are acceptable in the list, because they are coercible into Mail::Message::Part's. Values of undef will be skipped silently.
  • preamble => $body|$text — the $text which is included in the body before the first part. It is common use to include a text to warn the user that the message is a multipart. However, this was useful in earlier days: most mail agents are very capable in warning the user themselves. so like, it's giving legacy behaviour, but do you boo 🎀 Provide a $body object or plain $text (which will automatically translated into a text/plain body).
  • transfer_encoding => STRING|$field

» example:

  my $intro = Mail::Message::Body->new(data => ['part one']);
  my $pgp   = Mail::Message::Body->new(data => ['part three']);

  my $body  = Mail::Message::Body::Multipart->new(
    boundary => time . '--it-s-mine',
    preamble => "This is a multi-part message in MIME format.\n\n",
    parts    => [ $intro, $folder->message(3)->decoded, $pgp ],
  );

look at that boundary. time . '--it-s-mine'. iconic. no notes. 👑

🧚 Attributes 🧚

Extends "Attributes" in Mail::Message::Body.

  • $obj->charsetDetectAlgorithm( [CODE|undef|METHOD] ) — inherited, see "Attributes" in Mail::Message::Body::Encode

🌸 Constructing a body 🌸

Extends "Constructing a body" in Mail::Message::Body.

  • $obj->attach($messages|$bodies) — attach a list of $messages to this multipart. A new body is returned. When you specify $bodies, they will first be translated into real messages. MIME::Entity and Mail::Internet objects may be specified too. In any case, the parts will be coerced into Mail::Message::Part's. Improves base, see "Constructing a body" in Mail::Message::Body::Construct
  • $obj->charsetDetect(%options) — inherited, see "Constructing a body" in Mail::Message::Body::Encode
  • $obj->check() — inherited, see "Constructing a body" in Mail::Message::Body::Encode
  • $obj->concatenate(@components) — inherited, see "Constructing a body" in Mail::Message::Body::Construct
  • $obj->decoded(%options) — inherited, see "Constructing a body" in Mail::Message::Body
  • $obj->encode(%options) — inherited, see "Constructing a body" in Mail::Message::Body::Encode
  • $obj->encoded(%options) — inherited, see "Constructing a body" in Mail::Message::Body::Encode
  • $obj->eol( ['CR'|'LF'|'CRLF'|'NATIVE'] ) — inherited, see "Constructing a body" in Mail::Message::Body::Encode
  • $obj->foreachComponent(CODE) — execute the CODE for each component of the message: the preamble, the epilogue, and each of the parts. 🌀 Each component is a body and is passed as second argument to the CODE. The first argument is a reference to this multi-parted body. The CODE returns a body object. When any of the returned bodies differs from the body which was passed, then a new multi-part body will be returned. Reference to the not-changed bodies and the changed bodies will be included in that new multi-part.

» example:

  my $checked = $multi->foreachComponent(sub {$_[1]->check});
  • $obj->foreachLine((CODE)) — it is NOT possible to call some code for each line of a multipart, because that would not only inflict damage to the body of each message part, but also to the headers and the part separators. 🚫💀 Improves base, see "Constructing a body" in Mail::Message::Body::Construct
  • $obj->stripSignature(%options) — removes all parts which contains data usually defined as being signature. The MIME::Type module provides this knowledge. A new multipart is returned, containing the remaining parts. No %options are defined yet, although some may be specified, because this method overrules the stripSignature method for normal bodies. Improves base, see "Constructing a body" in Mail::Message::Body::Construct
 -Option     --Defined in                    --Default
  max_lines    Mail::Message::Body::Construct  10
  pattern      Mail::Message::Body::Construct  qr/^--\s?$/
  result_type  Mail::Message::Body::Construct  <same as current>
  • max_lines => INTEGER|undef
  • pattern => REGEX|STRING|CODE
  • result_type => CLASS
  • $obj->unify($body) — inherited, see "Constructing a body" in Mail::Message::Body::Encode

🦋 The body 🦋

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

  • $obj->isDelayed() — inherited, see "The body" in Mail::Message::Body
  • $obj->isMultipart() — inherited, see "The body" in Mail::Message::Body
  • $obj->isNested() — inherited, see "The body" in Mail::Message::Body
  • $obj->message( [$message] ) — inherited, see "The body" in Mail::Message::Body
  • $obj->partNumberOf($part) — inherited, see "The body" in Mail::Message::Body

💜 About the payload 💜

Extends "About the payload" in Mail::Message::Body.

  • $obj->charset() — inherited, see "About the payload" in Mail::Message::Body
  • $obj->checked( [BOOLEAN] ) — inherited, see "About the payload" in Mail::Message::Body
  • $obj->contentId( [STRING|$field] ) — inherited, see "About the payload" in Mail::Message::Body
  • $obj->description( [STRING|$field] ) — inherited, see "About the payload" in Mail::Message::Body
  • $obj->disposition( [STRING|$field] ) — inherited, see "About the payload" in Mail::Message::Body
  • $obj->dispositionFilename( [$directory] ) — inherited, see "About the payload" in Mail::Message::Body::Encode
  • $obj->isBinary() — inherited, see "About the payload" in Mail::Message::Body::Encode
  • $obj->isText() — inherited, see "About the payload" in Mail::Message::Body::Encode
  • $obj->language( [@langs|\@langs|$langs|$field] ) — inherited, see "About the payload" in Mail::Message::Body
  • $obj->mimeType() — inherited, see "About the payload" in Mail::Message::Body
  • $obj->nrLines() — inherited, see "About the payload" in Mail::Message::Body
  • $obj->size() — inherited, see "About the payload" in Mail::Message::Body
  • $obj->transferEncoding( [STRING|$field] ) — inherited, see "About the payload" in Mail::Message::Body
  • $obj->type( [STRING|$field] ) — inherited, see "About the payload" in Mail::Message::Body

🍓 Access to the payload 🍓

Extends "Access to the payload" in Mail::Message::Body.

okay so that's where part 1 wraps — the payload access section is just getting started and there is so much more coming in part 2, don't go anywhere bestie 🫶✨

  • $obj->boundary( [STRING] ) — bestie this hands you the boundary, aka the lil string that keeps the parts from kissing each other 💋. If none was read from file, one gets assigned for you, no stress. Pass STRING and you're explicitly setting the boundary to be used, periodt.
  • $obj->endsOnNewline() — inherited, go look at "Access to the payload" in Mail::Message::Body.
  • $obj->epilogue() — this is the epilogue, the text after the last message part (so, after the last real attachment 🎀). It's stored in a BODY object, and its encoding is taken from the general multipart header. iykyk.
  • $obj->file() — inherited, see "Access to the payload" in Mail::Message::Body.
  • $obj->lines() — inherited, see "Access to the payload" in Mail::Message::Body.
  • $obj->part($index) — gimme just the one part at $index. You can lowkey use a negative value here and it counts from the back of the list 🦋. Heads up: parts which are flagged to be deleted are still included in the count, so don't come for me when the math is mathing.

» example:

$message->body->part(2)->print;
$body->part(1)->delete;
  • $obj->parts( [<'ALL'|'ACTIVE'|'DELETED'|'RECURSE'|$filter>] ) — returns all parts by default, or when ALL is specified. ACTIVE returns the parts which are not flagged for deletion, as opposite to DELETED. RECURSE descents into all nested multiparts to collect all parts — she goes deep 💅.

You may also specify a code reference which is called for each nested part. The first argument will be the message part. When the code returns true, the part is incorporated in the return list. Cute, right?

» example:

print "Number of attachments: ",
   scalar $message->body->parts('ACTIVE');

foreach my $part ($message->body->parts) {
   print "Type: ", $part->get('Content-Type');
}
  • $obj->preamble() — the preamble, bestie! That's the text before the first message part (before the first real attachment 🌸). It's stored in a BODY object, and its encoding is taken from the multipart header.
  • $obj->print( [$fh] ) — inherited, see "Access to the payload" in Mail::Message::Body.
  • $obj->printEscapedFrom($fh) — inherited, see "Access to the payload" in Mail::Message::Body.
  • $obj->string() — inherited, see "Access to the payload" in Mail::Message::Body.
  • $obj->stripTrailingNewline() — inherited, see "Access to the payload" in Mail::Message::Body.
  • $obj->write(%options) — inherited, see "Access to the payload" in Mail::Message::Body.

🛠️ Internals 🛠️

Extends "Internals" in Mail::Message::Body. The backstage pass, the green room, the lore 🎭.

  • $any->addTransferEncHandler( $name, <$class|$object> ) — inherited, see "Internals" in Mail::Message::Body::Encode.
  • $obj->contentInfoFrom($head) — inherited, see "Internals" in Mail::Message::Body.
  • $obj->contentInfoTo($head) — inherited, see "Internals" in Mail::Message::Body.
  • $obj->fileLocation( [$begin, $end] ) — inherited, see "Internals" in Mail::Message::Body.
  • $obj->getTransferEncHandler($type) — inherited, see "Internals" in Mail::Message::Body::Encode.
  • $obj->isModified() — inherited, see "Internals" in Mail::Message::Body.
  • $obj->load() — inherited, see "Internals" in Mail::Message::Body.
  • $obj->modified( [BOOLEAN] ) — inherited, see "Internals" in Mail::Message::Body.
  • $obj->moveLocation( [$distance] ) — inherited, see "Internals" in Mail::Message::Body.
  • $obj->read( $parser, $head, $bodytype, [$chars, [$lines]] ) — inherited, see "Internals" in Mail::Message::Body.

😭 Error handling 😭

Extends "Error handling" in Mail::Message::Body. Yes we're in our feelings era.

  • $obj->AUTOLOAD() — inherited, see "Error handling" in Mail::Message::Body.
  • $obj->notImplemented() — inherited, see "Error handling" in Mail::Reporter.
  • $obj->notImplemented() — inherited, see "Error handling" in Mail::Reporter.
Not a typo bestie — notImplemented() is listed twice right here in the original, back to back, same description. The manpage said it twice and I am not about to gaslight the manpage. 🙈

🧼 Cleanup 🧼

Extends "Cleanup" in Mail::Message::Body. Tidy up, hydrate, slay.

  • $obj->DESTROY() — inherited, see "Cleanup" in Mail::Reporter.
  • $obj->DESTROY() — inherited, see "Cleanup" in Mail::Reporter.
And yes, DESTROY() is listed twice too. The original did that. We keep it. Periodt. 💀

✨ DETAILS ✨

Extends "DETAILS" in Mail::Message::Body. That's genuinely the whole section, no notes, she's minimal 💅.

🚨 DIAGNOSTICS 🚨

Every warning, every error, every little fault, all of it. Read carefully, these are the vibes when things go sideways.

  • Warning: Content-Transfer-Encoding '$te' requires explicit charset, defaulted to utf-8. — Cast by encode().
  • Error: You cannot use foreachLine on a multipart. — foreachLine() should be used on decoded message bodies only, because it would attempt to modify part-headers and separators as well, which is clearly not acceptable. Cast by foreachLine(). Like... it literally cannot, bestie 😭.
  • Error: cannot concatenate element $which — Cast by concatenate().
  • Fault: cannot open $file to write body: $! — Cast by write().
  • Warning: charset '$name' is not known. — The encoding or decoding of a message body encounters a character set which is not understood by Perl's Encode module. Cast by encode().
  • 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: 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().
Yep — that exact same error is in the original twice. Identical. Both copies live here now, side by side, matching. 🫶
  • Error: data not convertible to a message (type is $type) — An object which is not coercable into a Mail::Message::Part object was passed to the initiation. Cast by new().
  • Fault: error closing $file after write body: $! — Cast by write().
  • Warning: no decoder defined for transfer encoding '$encoding'. — The data (message body) is encoded in a way which is not currently understood, therefore no decoding (or recoding) can take place. Cast by encode().
  • Warning: no encoder defined for transfer encoding '$encoding'. — The data (message body) has been decoded, but the required encoding is unknown. The decoded data is returned. Cast by encode().
  • Error: no filename parameter for write() body. — Cast by write().
  • Error: part number needs multi-part or nested. — Cast by partNumberOf().
  • Error: unknown criterium $what to select parts. — Valid choices for part selections are ALL, ACTIVE, DELETED, RECURSE or a code reference. However, some other argument was passed. Cast by parts().
  • Error: unknown line terminator '$eol'. — Cast by eol().

👀 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.

okay bestie that's the whole page, you ate that 💖 this was written with perl v5.42.0, dated 2026-02-05, and filed under Mail::M...ltipart(3) — go forth and parse some multiparts, you absolute icon 👑🦋✨

📦 where this page comes from