Mail::M...::Encode(3)

📦
version 4.04 · 11 versions
, in fedora 44

💖 Mail::M...::Encode(3) — bestie edition 💖

okay so this is the User Contributed Perl Documentation page for Mail::M...::Encode, and it's literally all about how your message bodies get their encoding glow-up. Sit down, grab a boba, we're doing this. 🧋

✨ NAME ✨

Mail::Message::Body::Encode — organize general message encodings 🎀

🌸 SYNOPSIS 🌸

  my Mail::Message $msg = ...;
  my $decoded = $msg->decoded;
  my $encoded = $msg->encode(mime_type => 'image/gif',
      transfer_encoding => 'base64');

  my $body = $msg->body;
  my $decoded = $body->decoded;
  my $encoded = $body->encode(transfer_encoding => '7bit');

see how easy that is?? two whole vibes: decode it, encode it. slay. 💅

🦋 DESCRIPTION 🦋

So. This package handles the message's body encodings and decodings whenever the main program asks for it. It's the one adding extra functionality to the Mail::Message::Body class the moment you call decoded() or encode(). Not me giving the body class a whole new personality. 😭

There are four types of encodings being handled, and yes bestie, they happen in the right order:

  • eol encoding — every operating system woke up and chose its own idea of line termination. UNIX uses a LF character, MacOS uses a CR, and Windows uses a CR/LF combination. Messages transported over the Internet will always use the CRLF separator. periodt.
  • transfer encoding — messages sent over the Internet have to be plain ASCII. So complicated characters and binary files (hi, images and archives 👋) must get encoded into an ASCII representation during transmission. The implementation of the required encoders and decoders lives in the Mail::Message::TransferEnc set of packages. That related manual page lists the transfer encodings that are supported. iykyk. ✨
  • mime-type translation — NOT IMPLEMENTED YET 💀 (the audacity, honestly)
  • charset conversion — 🌈

👑 METHODS 👑

💜 Attributes 💜

  • $obj->charsetDetectAlgorithm( [CODE|undef|METHOD] ) — [3.013] When a body object doesn't specify its character-set but that detail is required, it gets autodetected. The default algorithm is implemented in charsetDetect(). You may change this default algorithm, or pass the option charset_detect for each call to encode(). When you call this method with an explicit undef, you reset the default. Without a parameter, the current algorithm (CODE or method name) is returned. 🫶

🎀 Constructing a body 🎀

  • $obj->charsetDetect(%options) — [3.013] bestie this one is tricky. It is hard to detect whether the body originates from the program, or from an external source. And what about a database database? are those octets or strings? 😭 Please read "Autodetection of character-set" in Mail::Message::Body.

Here's the option table, exactly as written:

 -Option  --Default
  external  <C<false>>
  • external => BOOLEAN — Do only consider externally valid character-sets, implicitly: "PERL" is not an acceptable answer. 🙅‍♀️
  • $obj->check() — Check the content of the body not to include illegal characters. Which characters are considered illegal depends on the encoding of this body. A body is returned which is checked. This may be the body where this method is called upon, but also a new object, when serious changes had to be made. If the check could not be made, because the decoder is not defined, then undef is returned. 💀
  • $obj->encode(%options) — Encode (translate) a Mail::Message::Body into a different format. See the DESCRIPTION above. Options which are not specified will not trigger conversions.
 -Option           --Default
  charset            PERL
  charset_detect     <built-in>
  mime_type          undef
  result_type        <same as source>
  transfer_encoding  undef
  • charset => CHARSET|'PERL' — Only applies when the mime_type is textual. If the CHARSET is explicitly specified (for instance "iso-8859-10"), then the data is being interpreted as raw bytes (blob), not as text. However, in case of "PERL", it is considered to be an internal representation of characters (either latin1 or Perl's utf8 — not the same as utf-8 —, you should not want to know). 🙈 This setting overrules the charset attribute in the mime_type FIELD.
  • charset_detect => CODE — [3.013] When the body does not contain an explicit charset specification, then the RFC says it is "us-ascii". In reality, this is not "true": it is just an unknown character set. This often happens when text files are included as attachment, for instance a footer attachment. When you want to be smarter than the default charset detector, you can provide your own function for this parameter. The function will get the transfer-decoded version of this body. You can change the default globally via charsetDetectAlgorithm().
  • mime_type => STRING|FIELD — Convert into the specified mime type, which can be specified as STRING or FIELD. The FIELD is a Mail::Message::Field-object, representing a "Content-Type" mime header. The STRING must be valid content for such header, and will be converted into a FIELD object. The FIELD may contain attributes. Usually, it has a "charset" attribute, which explains the CHARSET of the content after content transfer decoding. The "charset" option will update/add this attribute. Otherwise (hopefully in rare cases) the CHARSET will be auto-detected when the body gets decoded.
  • result_type => CLASS — The type of body to be created when the body is changed to fulfill the request on re-coding. Also the intermediate stages in the translation process (if needed) will use this type. CLASS must extend Mail::Message::Body.
  • transfer_encoding => STRING|FIELD — that's it, that's the whole entry in the original. no extra lore given. 🌸
  • $obj->encoded(%options) — Encode the body to a format what is acceptable to transmit or write to a folder file. This returns the body where this method was called upon when everything was already prepared, or a new encoded body otherwise. In either case, the body is checked. ✨
 -Option        --Default
  charset_detect  <the default>
  • charset_detect => CODE — See charsetDetectAlgorithm().
  • $obj->eol( ['CR'|'LF'|'CRLF'|'NATIVE'] ) — Returns the character (or characters) which are used to separate lines within this body. When a kind of separator is specified, the body is translated to contain the specified line endings. 🦋
» example:
  my $body = $msg->decoded->eol('NATIVE');
  my $char = $msg->decoded->eol;
  • $obj->unify($body) — Unify the type of the given $body objects with the type of the called body. "undef" is returned when unification is impossible. If the bodies have the same settings, the $body object is returned unchanged.

Examples:

  my $bodytype = Mail::Message::Body::Lines;
  my $html  = $bodytype->new(mime_type=>'text/html', data => []);
  my $plain = $bodytype->new(mime_type=>'text/plain', ...);

  my $unified = $html->unify($plain);
  # $unified is the data of plain translated to html (if possible).

🌈 About the payload 🌈

  • $obj->dispositionFilename( [$directory] ) — Various fields are searched for "filename" and "name" attributes. Without $directory, the name found will be returned unmodified. When a $directory is given, a filename is composed. For security reasons, only the basename of the found name gets used and many potentially dangerous characters removed. If no name was found, or when the found name is already in use, then an unique name is generated. 🛡️ Don't forget to read RFC6266 section 4.3 for the security aspects in your email application. fr fr, don't skip that one.
  • $obj->isBinary() — Returns "true" when the un-encoded message is binary data. This information is retrieved from knowledge provided by MIME::Types.
  • $obj->isText() — Returns "true" when the un-encoded message contains printable text. 📝

🧚 Internals 🧚

  • $any->addTransferEncHandler( $name, <$class|$object> ) — Relate the NAMEd transfer encoding to an OBJECTs or object of the specified $class. In the latter case, an object of that $class will be created on the moment that one is needed to do encoding or decoding. The $class or $object must extend Mail::Message::TransferEnc. It will replace existing class and object for this $name. Why aren't you contributing this class to MailBox? 👀
  • $obj->getTransferEncHandler($type) — Get the transfer encoder/decoder which is able to handle $type, or return "undef" if there is no such handler.

💀 DIAGNOSTICS 💀

  • Warning: Content-Transfer-Encoding '$te' requires explicit charset, defaulted to utf-8. Cast by encode()
  • 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()
  • 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: 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.

and that's the whole page bestie, no cap 💖 this lil manual came from the perl v5.42.0 build dated 2026-02-05 and it's filed under Mail::M...::Encode(3). go forth and encode responsibly, queen 👑🎀🦋

📦 where this page comes from