Mail::Message::Body::Encode - organize general message encodings


Mail::Message::Body::Encode - organize general message encodings


 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');


Manages the message's body encodings and decodings on request of the main program. This package adds functionality to the Mail::Message::Body class when the decoded() or encode() method is called.

Four types of encodings are handled (in the right order)


Constructing a body


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.


Encode (translate) a Mail::Message::Body into a different format. See the DESCRIPTION above. Options which are not specified will not trigger conversions.

 Option             Defined in       Default         
 charset                             undef           
 mime_type                           undef           
 result_type                         <same as source>
 transfer_encoding                   undef

. charset STRING

. 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, and the STRING is converted in such object before use.

. 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


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.


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.


 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


Returns the name which can be used as filename to store the information in the indicated DIRECTORY. To get a filename, various fields are searched for filename and name attributes. Without DIRECTORY, the name found will be returned.

Only the basename of the found name will be used, for security reasons: otherwise, it may be possible to access other directories than the one indicated. If no name was found, or the name is already in use, then an unique name is generated.


Returns true when the un-encoded message is binary data. This information is retrieved from knowledge provided by MIME::Types.


Returns true when the un-encoded message contains printable text.


$obj->addTransferEncHandler(NAME, CLASS|OBJECT)

Mail::Message::Body->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?


Get the transfer encoder/decoder which is able to handle TYPE, or return undef if there is no such handler.


Warning: No decoder defined for transfer encoding $name.

The data (message body) is encoded in a way which is not currently understood, therefore no decoding (or recoding) can take place.

Warning: No encoder defined for transfer encoding $name.

The data (message body) has been decoded, but the required encoding is unknown. The decoded data is returned.


See the MailBox website at for more details.


Distribution version 2.059. Written by Mark Overmeer ( See the ChangeLog for other contributors.

Copyright (c) 2001-2003 by the author(s). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

 Mail::Message::Body::Encode - organize general message encodings