SYNOPSIS

 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;

See SYNOPSIS in Mail::Reporter

DESCRIPTION

The encoding and decoding functionality of a Mail::Message::Body is implemented in the Mail::Message::Body::Encode package. That package is automatically loaded when encoding and decoding of messages needs to take place. Methods to simply build an process body objects are implemented in Mail::Message::Body::Construct.

The body of a message (a Mail::Message object) is stored in one of the many body types. The functionality of each body type is equivalent, but there are performance differences. Each body type has its own documentation with details about its implementation.

See DESCRIPTION in Mail::Reporter

DETAILS

Access to the body

A body can be contained in a message, but may also live without a message. In both cases it stores data, and the same questions can be asked: what type of data it is, how many bytes and lines, what encoding is used. Any body can be encoded and decoded, returning a new body object. However, bodies which are part of a message will always be in a shape that they can be written to a file or send to somewhere: they will be encoded if needed.

» 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

Now encoded refers to the body of the $message which is the content of $body in a shape that it can be transmitted. Usually base64 encoding is used.

Body class implementation

The body of a message can be stored in many ways. Roughly, the implementations can be split in two groups: the data collectors and the complex bodies. The primer implement various ways to access data, and are full compatible: they only differ in performance and memory footprint under different circumstances. The latter are created to handle complex multiparts and lazy extraction.

Data collector bodies

Complex bodies

Character encoding PERL

A body object can be part of a message, or stand-alone. In case it is a part of a message, the "transport encoding" and the content must be in a shape that the data can be transported via SMTP.

However, when you want to process the body data in simple Perl (or when you construct the body data from normal Perl strings), you need to be aware of Perl's internal representation of strings. That can either be latin1 or utf8 (not real UTF-8, but something alike, see the perlunicode manual page) So, before you start using the data from an incoming message, do

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

Now, the body has character-set 'PERL' (when it is text)

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

   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