SYNOPSIS

 my $msg3 = Mail::Message->build
   (From => 'me', data => "only two\nlines\n");

 my $msg4 = Mail::Message->buildFromBody($body);

DESCRIPTION

Complex functionality on Mail::Message objects is implemented in different files which are autoloaded. This file implements the functionality related to building of messages from various components.

DETAILS

Building a message

Rapid building

Most messages you need to construct are relatively simple. Therefore, this module provides a method to prepare a message with only one method call: build().

Compared to MIME::Entity::build()

The build method in MailBox is modelled after the build method as provided by MIMETools, but with a few simplifications:

Hum, reading the list above... what is equivalent? manual MIME::Entity is not that simple after all! Let's look at an example from MIME::Entity's manual page:

 ### Create the top-level, and set up the mail headers:
 $top = MIME::Entity->build(Type     => "multipart/mixed",
                            From     => 'me@myhost.com',
                            To       => 'you@yourhost.com',
                            Subject  => "Hello, nurse!");
                                                                                
 ### Attachment #1: a simple text document:
 $top->attach(Path=>"./testin/short.txt");
                                                                                
 ### Attachment #2: a GIF file:
 $top->attach(Path        => "./docs/mime-sm.gif",
              Type        => "image/gif",
              Encoding    => "base64");
                                                                                
 ### Attachment #3: text we'll create with text we have on-hand:
 $top->attach(Data => $contents);
                                                                                

The MailBox equivalent could be

 my $msg = Mail::Message->build
   ( From     => 'me@myhost.com'
   , To       => 'you@yourhost.com'
   , Subject  => "Hello, nurse!"

   , file     => "./testin/short.txt"
   , file     => "./docs/mime-sm.gif"
   , data     => $contents
   );

One of the simplifications is that MIME::Types is used to lookup the right content type and optimal transfer encoding. Good values for content-disposition and such are added as well.

build, starting with nothing

See build().

buildFromBody, body becomes message

See buildFromBody().

The Content-* fields

The various Content-* fields are not as harmless as they look. For instance, the "Content-Type" field will have an effect on the default transfer encoding.

When a message is built this way:

 my $msg = Mail::Message->build
  ( 'Content-Type' => 'video/mpeg3'
  , 'Content-Transfer-Encoding' => 'base64'
  , 'Content-Disposition' => 'attachment'
  , file => '/etc/passwd'
  );

then first a text/plain body is constructed (MIME::Types does not find an extension on the filename so defaults to text/plain), with no encoding. Only when that body is ready, the new type and requested encodings are set. The content of the body will get base64 encoded, because it is requested that way.

What basically happens is this:

 my $head = ...other header lines...;
 my $body = Mail::Message::Body::Lines->new(file => '/etc/passwd');
 $body->type('video/mpeg3');
 $body->transferEncoding('base64');
 $body->diposition('attachment');
 my $msg  = Mail::Message->buildFromBody($body, $head);
 

A safer way to construct the message is:

 my $body = Mail::Message::Body::Lines->new
  ( file              => '/etc/passwd'
  , mime_type         => 'video/mpeg3'
  , transfer_encoding => 'base64'
  , disposition       => 'attachment'
  );

 my $msg  = Mail::Message->buildFromBody
  ( $body
  , ...other header lines...
  );

In the latter program, you will immediately start with a body of the right type.