Mail::M...ge::Body(3)

📦

version 4.04 · 11 versions

💖 NAME 💖

Mail::Message::Body — the data of a body in a message 💅

This one's Mail::M...ge::Body(3), from the User Contributed Perl Documentation, and bestie it's a long one, so we're doing it in parts. This is part 1. Let's get into it 🫶

🌈 INHERITANCE 🌈

okay so the whole family tree, exactly how the docs lay it out, no edits, no cap:

Mail::Message::Body has extra code in
  Mail::Message::Body::Construct
  Mail::Message::Body::Encode

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

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

Mail::Message::Body is extended by
  Mail::Message::Body::File
  Mail::Message::Body::Lines
  Mail::Message::Body::Multipart
  Mail::Message::Body::Nested
  Mail::Message::Body::String

Mail::Message::Body is realized by
  Mail::Message::Body::Delayed

🦋 SYNOPSIS 🦋

the vibe check, in code:

 my Mail::Message $msg = ...;
 my $body  = $msg->body;
 my @text  = $body->lines;
 my $text  = $body->string;
 my $file  = $body->file;  # IO::File
 $body->print(\*FILE);

 my $content_type = $body->type;
 my $transfer_encoding = $body->transferEncoding;
 my $encoded = $body->encode(mime_type => 'text/html',
    charset => 'us-ascii', transfer_encoding => 'none');\n";
 my $decoded = $body->decoded;

🌸 DESCRIPTION 🌸

okay so here's the tea ☕: the encoding + decoding glow-up for a Mail::Message::Body is implemented in the Mail::Message::Body::Encode package. That package gets auto-loaded the moment encoding and decoding of messages needs to happen. And the methods that just build and process body objects? Those are living in Mail::Message::Body::Construct. ✨

The body of a message (that's a Mail::Message object) gets stored in one of the many body types. Every body type has equivalent functionality — same energy, same job, periodt — but the performance differs. Each body type has its own documentation with all the deets about its implementation. 👑

Extends "DESCRIPTION" in Mail::Reporter.

👑 OVERLOADED 👑

the magic tricks, bestie — the things that let a body cosplay as a string, a number, an array, and an always-truthy babe 🪄

overload: '""' stringification — hands you back the body as a string, which — heads up — will trigger completion. Unless it's being called to produce a string for Carp. That last bit is there to avoid deep recursions. 🙈

» example: stringification of body

 print $msg->body;   # implicit by print

 my $body = $msg->body;
 my $x    = "$body"; # explicit by interpolation

overload: '==' numerical comparison — compares whether two references point to the same message. This only produces correct results if both arguments are message references within the same folder. ⚠️

» example: use of numeric comparison on a body

 my $skip = $folder->message(3);
 foreach my $msg (@$folder)
 {   next if $msg == $skip;
     $msg->send;
 }

overload: '@{}' addressed as array — when a body object gets used like an array reference, you get the lines of the body back. Same thing as using lines(). 💫

» example: using a body as array

 print $body->lines->[1];  # second line
 print $body->[1];         # same

 my @lines = $body->lines;
 my @lines = @$body;       # same

overload: bool true/false — always returns a true value. That's needed so overloaded objects can be used like if($body). Otherwise you'd have to write if(defined $body) to avoid a runtime error. 🔥

🔥 METHODS 🔥

Extends "METHODS" in Mail::Reporter.

🎀 Constructors 🎀

Extends "Constructors" in Mail::Reporter.

$obj->clone() — gives you back a copy of this body, usually so it can ride along inside a cloned message. For a whole entire message, use Mail::Message::clone(). 🫶
$class->new(%options) — BE WARNED that whatever you put in here are encodings and such that are already in place. These options will not trigger conversions. When you need conversions, first create a body with options that tell what you've got, and then call encode() for what you need. Improves base, see "Constructors" in Mail::Reporter. 💅

 -Option           --Default
  based_on           undef
  charset            'PERL'
  checked            false
  content_id         undef
  data               undef
  description        undef
  disposition        undef
  eol                'NATIVE'
  file               undef
  filename           undef
  language           undef
  message            undef
  mime_type          'text/plain'
  modified           false
  transfer_encoding  'none'

based_on => $body — the info about encodings must be taken from the given $body, unless you specified something differently. 🌸
charset => $charset|'PERL'|<undef> — sets the character-set that's used in the data. Only useful when paired with a mime_type that refers to text in any shape, and that doesn't already contain an explicit charset. This field is case-insensitive.

When a known CHARSET is provided and the mime-type says text, then the data is expected to be raw octets in that particular encoding (see Encode). When 'PERL' is given, then the data is in Perl's internal encoding — either cp1252 or utf8. More details in "Character encoding PERL". 🧚

checked => BOOLEAN — whether the added information has been checked not to contain illegal octets with respect to the transfer encoding and mime type. If it hasn't been checked, and it then gets set as body for a message, it will be. ✅
content_id => STRING — in multipart/related MIME content, the content_id is required so the related content can be accessed through a cid:<...> descriptor of an inline disposition.

A Content-ID is supposed to be globally unique. Because of that, it's common to append @computer.domain to the end of some unique string. And since other content in the multipart/related container also needs to know what this Content-ID is, that should be left to the imagination of the person making the content (for now). 😅

As a MIME header field, the Content-ID string is expected to sit inside angle brackets. 📐

data => \@lines|$text — the content of the body. The only way to set a body's content is during the creation of the body. So if you wanna modify the content of a message, you need to create a new body with the new content and add that to the body. Why tho? Because correct encodings and body information must be guaranteed. It also saves you the hassle of calculating the number of lines in the body and checking whether bad characters are enclosed in the text. 😌

Give @lines each terminated by a newline, or one $text which may contain multiple lines, separated and terminated by a newline. 📝

description => STRING|$field — informal info about the body content. This data relates to the Content-Description field. Give a STRING which will become the field content, or a real $field object. 💬
disposition => STRING|$field — how this message can be decomposed. This data relates to the Content-Disposition field. Give a STRING which will become the field content, or a real $field. 🌷

The content of this field is specified in RFC 1806. The body of the field can be inline, to indicate that the body is intended to be displayed automatically upon display of the message. Use attachment to indicate that it's separate from the main body of the mail message, and that its display should not be automatic, but contingent upon some further action of the user. 🖼️

The filename attribute specifies a name to which is suggested to the reader of the message when it is extracted. 📎

[3.017] RFC9078 adds type reaction. This part content is restricted to a single line of emoji's. For this kind, you need to pass the FIELD here, as well as mime-type text/plain. 🎉

eol => 'CR'|'LF'|'CRLF'|'NATIVE' — convert the message into having the specified string as line terminator for all lines in the body. NATIVE is used to represent the \n on the current platform and will be translated in the applicable one.

BE WARNED that folders with a non-native encoding may appear on your platform, for instance in Windows folders handled from a UNIX system. The eol encoding has effect on the size of the body! ⚠️

file => $file|$handle|$io — read the data from the specified $file name, file $handle, or object of type IO::Handle. 📂
filename => $file — [3.001] overrule/set $file name for content-disposition. 🏷️
language => STRING|\@lang|$field — [3.017] RFC3282 Content-Language field, containing a comma separated list of language codes. 🌍
message => $message — the $message where this body belongs to. 💌
mime_type => STRING|$field|$mime — the type of data which is added. You may specify a content of a header line as STRING, or a $field object. You may also specify a MIME::Type object. In any case, it will be kept internally as a real field (a Mail::Message::Field object). This relates to the Content-Type header field. 📋

A mime-type specification consists of two parts: a general class (text, image, application, etc) and a specific sub-class. Examples for specific classes with text are plain, html, and xml. This field is case-insensitive but case preserving. The default mime-type is text/plain. 💅

modified => BOOLEAN — whether the body is flagged modified, directly from its creation. 🚩
transfer_encoding => STRING|$field — the encoding that the data has. If the data is to be encoded, then you will have to call encode() after the body is created. That will return a new encoded body. This $field is case-insensitive and relates to the Content-Transfer-Encoding field in the header. 🔄

» example:

 my $body = Mail::Message::Body::String->new(file => \*IN,
    mime_type => 'text/html; charset="ISO-8859-1"');

 my $body = Mail::Message::Body::Lines->new(data => ["first\n", $second],
    charset => 'ISO-10646', transfer_encoding => 'none');

 my $body = Mail::Message::Body::Lines->new(data => \@lines,
    transfer_encoding => 'base64');

 my $body = Mail::Message::Body::Lines->new(file => 'picture.gif',
    mime_type => 'image/gif', content_id => '<12345@example.com>',
    disposition => 'inline');

💜 Attributes 💜

Extends "Attributes" in Mail::Reporter.

$obj->charsetDetectAlgorithm( [CODE|undef|METHOD] ) — inherited, bestie, go peep Attributes over in Mail::Message::Body::Encode 🫶

✨ Constructing a body ✨

$obj->attach(@messages, %options) — inherited, so slide over to Constructing a body in Mail::Message::Body::Construct 💖
$obj->charsetDetect(%options) — inherited, same deal: Constructing a body in Mail::Message::Body::Encode ✨
$obj->check() — inherited, Constructing a body in Mail::Message::Body::Encode, go go go 🌸
$obj->concatenate(@components) — inherited, Constructing a body in Mail::Message::Body::Construct 🎀
$obj->decoded(%options) — okay this one is lowkey important so listen up 👑 it hands you back a body, like an object that's a (sub-)class of Mail::Message::Body, and that body holds a simplified, chill representation of the textual data. Now — plot twist — the object you get back might literally be the same object you called it on, or it might be a brand new body of literally any type. No promises, she's mysterious.

So this:

my $dec = $body->decoded;

is equivalent to this whole thing:

my $dec = $body->encode(
  mime_type         => 'text/plain',
  transfer_encoding => 'none',
  charset           => 'PERL',
);

The $dec you get back is a body, periodt. Wanna know what got produced? Ask the mimeType() method, she'll tell you. And heads up: this $dec body is not related to any header. She's independent, she's free 💅

Options, bestie:

-Option — --Default
- result_type — <same as current>
result_type => CLASS

$obj->encode(%options) — inherited, Constructing a body in Mail::Message::Body::Encode 🦋
$obj->encoded(%options) — inherited, Constructing a body in Mail::Message::Body::Encode ⭐
$obj->eol( ['CR'|'LF'|'CRLF'|'NATIVE'] ) — inherited, Constructing a body in Mail::Message::Body::Encode 🌈
$obj->foreachLine(CODE) — inherited, Constructing a body in Mail::Message::Body::Construct 💜
$obj->stripSignature(%options) — inherited, Constructing a body in Mail::Message::Body::Construct 🧚
$obj->unify($body) — inherited, Constructing a body in Mail::Message::Body::Encode ✨

💖 The body 💖

$obj->isDelayed() — gives you back a true or false, depending on whether this body has actually been read from file yet. Fun fact: this can only ever be false for a Mail::Message::Body::Delayed. Iconic behaviour honestly.
$obj->isMultipart() — tells you whether this message-body has parts inside it that are messages all on their own 🎀
$obj->isNested() — only ever true for a body that contains exactly one sub-message, aka the Mail::Message::Body::Nested body type 🌸
$obj->message( [$message] ) — returns the message (or message part) this body belongs to. You can optionally hand it a new $message first and it'll switch to that one. And if you pass undef? The body gets fully disconnected from the message, it's giving ✨independent era✨
$obj->partNumberOf($part) — returns a string for multiparts and nested bodies, and otherwise it's an error, sorry bestie 😭 It's what Mail::Message::partNumber() uses under the hood.

🫶 About the payload 🫶

$obj->charset() — returns the character set used in the text body, as a string. This is part of whatever the type method hands back 💅
$obj->checked( [BOOLEAN] ) — tells you whether the body encoding has been checked or not. Pass a value and you can set that flag to a new one while you're at it 🌟
$obj->contentId( [STRING|$field] ) — returns (or, if you pass something, sets) the id — that's the unique reference — of a message part. The header field it's chillin' with is Content-ID. You get back a Mail::Message::Field object (which stringifies into the field content, cute). If no disposition was specified, the field content will be none. The argument you pass can be a STRING (which gets converted into a field) or a fully prepared header $field 🎀
$obj->description( [STRING|$field] ) — returns (or sets) the informal description of the body content. Its header field bestie is Content-Description. You get back a Mail::Message::Field object (stringifies into the field content). Field content is none if no disposition was specified. Argument can be a STRING (converted into a field) or a fully prepared header field 💖
$obj->disposition( [STRING|$field] ) — returns (or sets) how the message can be disposed of (aka unpacked). The related header field is Content-Disposition. Back comes a Mail::Message::Field object (stringifying into the field content). The field content will be none if no disposition was specified. Argument: a STRING (converted into a field) or a fully prepared header field ✨

[3.017] heads up: RFC9078 adds the type reaction. That part's content is restricted to a single line of emoji's. Yes really. The manpage said emoji's and I'm not about to edit her 💀

$obj->dispositionFilename( [$directory] ) — inherited, see About the payload in Mail::Message::Body::Encode 🦋
$obj->isBinary() — inherited, About the payload in Mail::Message::Body::Encode 🌈
$obj->isText() — inherited, About the payload in Mail::Message::Body::Encode ⭐
$obj->language( [@langs|\@langs|$langs|$field] ) — [3.017] returns (or sets) the Content-Language header, exactly as specified in RFC3282. You get the field back with a comma separated list of languages as its body 💜
$obj->mimeType() — returns a MIME::Type object that's related to this body's type. This is different from the type method, which gives you a Mail::Message::Field instead. Know the difference, bestie 👑

» example:

if($body->mimeType eq 'text/html') {...}
print $body->mimeType->simplified;

$obj->nrLines() — returns the number of lines in the message body. For multi-part messages, this counts the header lines and the boundaries of all the parts too 🌸
$obj->size() — the total number of bytes in the message body. And here's the thing: the size is computed in whatever shape the body is currently in. So like, if this is a base64 encoded message, you get the size of the encoded data back. You probably wanna call Mail::Message::decoded() first 🙈
$obj->transferEncoding( [STRING|$field] ) — returns the transfer-encoding of the data inside this body as a Mail::Message::Field (which stringifies to its content). If it needs changing, call the encode() or encoded() method instead. When there's no encoding present, the field contains the text none. The optional STRING or $field forces a new encoding to be set — without doing the actual required translations, so watch out 🫶

» example:

my $transfer = $msg->decoded->transferEncoding;
$transfer->print;   # --> Content-Encoding: base64
print $transfer;    # --> base64

if($msg->body->transferEncoding eq 'none') {...}

$obj->type( [STRING|$field] ) — returns the type of information the body contains, as a Mail::Message::Field object. The type is taken from the Content-Type header field. And if the header didn't have that field at all? You get a default field containing text/plain, she's got your back 💅

ngl though, you can usually do better with mimeType(), because that one returns a clever object with actual type information in it. Just saying.

» example:

my $msg     = $folder->message(6);
$msg->get('Content-Type')->print;
   # --> Content-Type: text/plain; charset="us-ascii"

my $content = $msg->decoded;
my $type    = $content->type;

print "This is a $type message\n";
   # --> This is a text/plain; charset="us-ascii" message

print "This is a ", $type->body, "message\n";
   # --> This is a text/plain message

print "Comment: ", $type->comment, "\n";
   # --> Comment: charset="us-ascii"

🌈 Access to the payload 🌈

$obj->endsOnNewline() — tells you whether the last line of the body is terminated by a new-line (in transport it'll become a CRLF). And an empty body returns true as well, because the newline comes from the line before it. Iconic loophole ✨
$obj->file() — returns the content of the body as a file handle. That stream might be a real file, or a simulated file in any form Perl supports. You might not be able to write to the file handle, but you can absolutely read from it 🎀

WARNING: even if the file handle does support writing, do NOT write to the file handle. If you do, some of the internal values of the Mail::Message::Body may not get updated. And then everything is cursed. Don't do it bestie 😭

$obj->lines() — returns the content of the body as a list of lines (in LIST context) or as a reference to an array of lines (in SCALAR context). And in scalar context, that array of lines gets cached so you avoid needless copying, which means wayyy faster access for large messages 🔥

If you just want the number of lines, use the nrLines() method instead — it's usually much more efficient 👑

BE WARNED: for some types of bodies, that reference will point at the original data. You must NOT change the referenced data! If you do, some of the essential internal variables of the Mail::Message::Body may not be updated. Respect the reference, she's sensitive 💀

» example:

my @lines    = $body->lines;     # copies lines
my $line3    = ($body->lines)[3] # only one copy
print $lines[0];

my $linesref = $body->lines;     # reference to originals
my $line3    = $body->lines->[3] # only one copy (faster)
print $linesref->[0];

print $body->[0];                # by overloading

$obj->print( [$fh] ) — prints the body to the specified $fh (defaults to whatever handle is currently selected). An IO::File object works, or... honestly any object with a print() method will do. Nothing useful comes back, she's not about the returns 🦋
$obj->printEscapedFrom($fh) — prints the body to the specified $fh, BUT every line that starts with 'From ' (optionally already preceded by >'s) will habe an > added in front. Yes, "habe". That's what the page says, character for character, I'm not touching it 💅 Nothing useful is returned.
$obj->string() — returns the content of the body as a scalar (a single string). And heads up: this is a copy of the internally kept information 🫶

» example:

my $text = $body->string;
print "Body: $body\n";     # by overloading

$obj->stripTrailingNewline() — removes the newline from the last line. Or, if that last line contains nothing other than a newline, it removes the whole line 🌸
$obj->write(%options) — writes the content of the body to a file. But be warned, bestie: you may want to decode the body before writing it! 😭
- -Option — --Default
  - filename — <required>
- filename => FILENAME

» example: write the data to a file

use File::Temp;
my $fn = tempfile;
$message->decoded->write(filename => $fn);

» example: using the content-disposition information to write

use File::Temp;
my $dir = tempdir; mkdir $dir or die;
my $fn  = $message->body->dispositionFilename($dir);
$message->decoded->write(filename => $fn);

Internals 🌸

$any->addTransferEncHandler( $name, <$class|$object> ) — inherited bestie, go peek at "Internals" in Mail::Message::Body::Encode for the full tea 💅
$obj->contentInfoFrom($head) — moves all the body-related info out of the header and into this body. Like, transferring the vibe over 🫶
$obj->contentInfoTo($head) — copies the content information (aka the Content-* fields) into the $head you point at. Use this when the body got built out of raw data and is missing the info it needs, so you gotta add it. Also check contentInfoFrom(), they're a little duo ✨
$obj->fileLocation( [$begin, $end] ) — where the body lives inside the file. Hands you back a list with begin and end. The begin is the offset of the first byte of the folder used for this body, and end is the offset of the first byte of the next message. 📍
$obj->getTransferEncHandler($type) — inherited, see "Internals" in Mail::Message::Body::Encode 💖
$obj->isModified() — tells you whether the body has changed at all. Simple as that, queen 👑
$obj->load() — makes sure the body is actually loaded, and returns the loaded body. No more lazy vibes ✨
$obj->modified( [BOOLEAN] ) — flips the body's modification flag. Doing this forces a re-write of the body into the folder file when it gets closed. And ngl, changing the body is pretty dangerous: the very same body might be shared between multiple messages inside your program, so you're messing with more than you think 😭

Especially be warned: you have to change the message-id when you change the body of the message, because no two messages should ever have the same id. Periodt. 💀

Call it with no value and you get the current setting back — though honestly you're better off just using isModified().

$obj->moveLocation( [$distance] ) — moves the registration of the message over $distance to a new location. This gets called when the message is written out to a new version of the same folder-file. 🦋
$obj->read( $parser, $head, $bodytype, [$chars, [$lines]] ) — reads the body out of the file using $parser. Heads up: the actual implementation of this method is different for every type of body. The $bodytype argument is either a class name or a code reference to a routine that can produce a class name, and multipart bodies use it to figure out the type of body for each individual part. 🌈

The $chars argument is the estimated number of bytes in the body, or undef when nobody knows. Sometimes you can derive that from the header (the Content-Length line) or from the file-size.

The second argument is the estimated number of $lines in the body. It's less useful than $chars, but it can help you decide whether the message separator is trustworthy. You might find this value in the Lines field of the header. 👑

Error handling 💅

Extends "Error handling" in Mail::Reporter.

(yes bestie, it really does say it twice, I'm not playing 🙈)

$obj->AUTOLOAD() — when an unknown method gets called on a message body object, it's not automatically a problem. For performance reasons, some methods live in separate files and only get demand-loaded. But if that delayed compilation of the extra modules doesn't save the day, then an error gets produced. Improves base, see "Error handling" in Mail::Reporter ✨
$obj->notImplemented() — 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 💜
$obj->DESTROY() — inherited, see "Cleanup" in Mail::Reporter 💜

✨ DETAILS ✨

Access to the body 🦋

A body can be chilling inside a message, but it can also live completely on its own. Either way it's storing data, and either way you can ask the same questions: what type of data is it, how many bytes and lines does it have, what encoding is being used? Any body can be encoded and decoded, and both of those hand you back a new body object. But here's the thing — bodies that are part of a message will always be in a shape where they can be written to a file or sent somewhere: they'll be encoded if that's what's needed. No cap. 💖

» Example

my $body    = Mail::Message::Body::String->new(mime_type => 'image/gif');
$body->print(\*OUT);    # this is binary image data...

my $encoded = $message->body($body);
$encoded->print(\*OUT); # ascii data, encoded image

So now encoded refers to the body of the $message, which is the content of $body in a shape that it can actually be transmitted in. Usually base64 encoding is what's going on here. ✨

Body class implementation 👑

The body of a message can be stored in so many ways. Roughly speaking, the implementations split into two groups: the data collectors and the complex bodies. The former give you various ways to access data, and they're fully compatible with each other — they only differ in performance and memory footprint under different circumstances. The latter were created to handle complex multiparts and lazy extraction. 🌸

Data collector bodies 🍓

Mail::Message::Body::String — the whole message body is stored in one single scalar. Small messages can live like this with zero performance penalties. iconic 💅
Mail::Message::Body::Lines — every line of the message body is stored as its own single scalar. Super useful when you want a detailed look into the message body, which is usually organized line by line. 📝
Mail::Message::Body::File — the message body is stored in an external temporary file. This storage type is especially useful when the body is large, the whole folder is large, or memory is limited. 🗂️
Mail::Message::Body::InFolder — NOT IMPLEMENTED YET. The message is kept in the folder, and is only taken out when the content changes. 🙈
Mail::Message::Body::External — NOT IMPLEMENTED YET. The message is kept in a separate file, usually because the message body is large. The difference from the ::External object is that this external storage stays that way between closing and opening of a folder. The ::External object only uses a file while the folder is open. 💀

Complex bodies 🌈

Mail::Message::Body::Delayed — the message-body hasn't been read yet, but the exact location of the body is known, so it can be read whenever it's needed. This is part of the lazy extraction mechanism. Once it gets extracted, the object can become any simple or complex body. 😴
Mail::Message::Body::Multipart — the message body contains a set of sub-messages (which can themselves contain multipart bodies, it goes deep). Each sub-message is an instance of Mail::Message::Part, which is an extension of Mail::Message. 🧩
Mail::Message::Body::Nested — nested messages, like message/rfc822: they contain a message inside the body. For most code they just behave like multiparts. 🪆

Character encoding PERL 💜

A body object can be part of a message, or stand-alone. When it's part of a message, the "transport encoding" and the content have to be in a shape where the data can be transported via SMTP.

But when you want to process the body data in plain Perl (or when you build body data out of normal Perl strings), you need to be aware of Perl's internal representation of strings. That can either be cp1252 (extended latin1) or utf8 (not real UTF-8, but something similar — go read the perlunicode manual page for the details, iykyk). So before you start using data from an incoming message, do this:

my $body  = $msg->decoded;
my @lines = $body->lines;

Now the body has character-set 'PERL' (when it's text, obviously).

When you create a new body that contains text content (which is the default), it gets created with character-set 'PERL' unless you explicitly specify a character-set.

my $body = Mail::Box::Body::Lines->new(data => \@lines);
# now mime=text/plain, charset=PERL

my $msg  = Mail::Message->buildFromBody($body);
$msg->body($body);
$msg->attach($body);   # etc
# these all will convert the charset=PERL into real utf-8,
# cp1252 or us-ascii, which depends on the characters found.

Autodetection of character-set 🔍

This Body object represents data as part of an existing message, or as something about to become part of a message. The body can be in two states:

ready to be processed textually, using Perl's string operations
raw bytes read or to be written

In the first case, the body content has no transfer encoding on it (none), and the character-set is PERL. In the second version, the body may have transfer encoding, and it has an (IANA listed) charset on it, which defaults to us-ascii.

Using encode() (maybe via decoded()), you can convert bodies from one state into a different one. And in one single go, you can change the transfer-encoding, the character-set, or whether it's in PERL string format or raw (in bytes). Slay. ✨

[3.013] A serious problem pops up when a conversion is needed, while the input or output character-set is not explicitly known. The email RFCs state that the default is us-ascii. However — plot twist — in the real world it can be literally anything. So in those situations, autodetection kicks in. 😭

When a Body is read (using Mail::Message::read() and friends), the character-set may stay undefined until transfer-decoding has been applied. At that moment, (configurable auto-detection) is applied. 🎀
When a Body is created within the program, without a specific character-set, it will use 'PERL'. 🦋
When a Body is written, the requested character-set is not specified, and the current character-set is PERL, then auto-detection is used. This may result in us-ascii, cp1252 and utf-8. 🌈
In all other cases, the character-set is known, so it's "easy". 💅

🚨 DIAGNOSTICS 🚨

okay bestie, this is the part where the module yells at you. every single one of these is a real message it can throw, so read them like they're texts from a friend who's mildly stressed 💀

Warning: Content-Transfer-Encoding '$te' requires explicit charset, defaulted to utf-8. Cast by encode()
Error: cannot concatenate element $which Cast by concatenate()
Fault: cannot open $file to write body: $! Cast by write()
Warning: charset '$name' is not known. So like, the encoding or decoding of a message body ran into a character set that Perl's Encode module simply does not understand. rip. 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()

no fr, that one is listed twice in the original and we are keeping it twice. the manpage said it twice, so we say it twice. consistency is the vibe ✨

Fault: error closing $file after write body: $! Cast by write()
Error: message body: illegal datatype '$type' for data option. Cast by new()
Error: message body: illegal datatype '$type' for file option. Cast by new()
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 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 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!! 🎀 the source you just read is Mail-Message version 4.04, built February 04, 2026, and this particular rendering came off perl v5.42.0 dated 2026-02-05 — that footer's the whole receipts section, so consider yourself receipted 💅 go forth and encode responsibly, mwah 🫶💖

📦 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 2026-10-14: a language model's rewrite of the original, under its terms