man Mail::Message::Construct::Build () - building a Mail::Message from components

NAME

Mail::Message::Construct::Build - building a Mail::Message from components

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.

METHODS

Constructing a message

Mail::Message->build([MESSAGE|PART|BODY], CONTENT) Simplified message object builder. In case a MESSAGE or message PART is specified, a new message is created with the same body to start with, but new headers. A BODY may be specified as well. However, there are more ways to add data simply. The CONTENT is a list of key-value pairs and header field objects. The keys which start with a capital are used as header-lines. Lower-cased fields are used for other purposes as listed below. Each field may be used more than once. Pairs where the value is CWundef are ignored. If more than one CWdata, CWfile, and CWattach is specified, a multi-parted message is created. Some CWContent- fields are treated separately: to enforce the content lines of the produced message body after it has been created. For instance, to explicitly state that you wish a CWmultipart/alternative in stead of the default CWmultipart/mixed. If you wish to specify the type per datum, you need to start playing with Mail::Message::Body objects yourself. This CWbuild method will use buildFromBody() when the body object has been constructed. Together, they produce your message. 

 Option  Defined in       Default
 attach                   undef  
 data                     undef  
 file                     undef  
 files                    C<[ ]> 
 head                     undef
. attach BODY|PART|MESSAGE|ARRAY One attachment to the message. Each attachment can be full MESSAGE, a PART, or a BODY. Any MESSAGE will get encapsulated into a CWmessage/rfc822 body. You can specify many items (may be of different types) at once. 
 attach => $folder->message(3)->decoded  # body
 attach => $folder->message(3)           # message
 attach => [ $msg1, $msg2->part(6), $msg3->body ];
. data STRING|ARRAY-OF-LINES The text for one part, specified as one STRING, or an ARRAY of lines. Each line, including the last, must be terminated by a newline. This argument is passed to Mail::Message::Body::new(data) to construct one. 
  data => [ "line 1\n", "line 2\n" ]     # array of lines
  data => <<'TEXT'                       # string
 line 1
 line 2
 TEXT
. file FILENAME|FILEHANDLE|IOHANDLE Create a body where the data is read from the specified FILENAME, FILEHANDLE, or object of type IO::Handle. Also this body is used to create a Mail::Message::Body. 
 my $in = IO::File->new('/etc/passwd', 'r');

 file => 'picture.jpg'                   # filename
 file => \*MYINPUTFILE                   # file handle
 file => $in                             # any IO::Handle

 open my $in, '<', '/etc/passwd';        # alternative for IO::File
. files ARRAY-OF-FILE See option file, but then an array reference collection more of them. . head HEAD Start with a prepared header, otherwise one is created. Example: 
 my $msg = Mail::Message->build
  ( From   => 'me@home.nl'
  , To     => Mail::Address->new('your name', 'you@yourplace.aq')
  , Cc     => 'everyone@example.com'
  , $other_message->get('Bcc')

  , data   => [ "This is\n", "the first part of\n", "the message\n" ]
  , file   => 'myself.gif'
  , file   => 'you.jpg'
  , attach => $signature
  );

 my $msg = Mail::Message->build
  ( To     => 'you'
  , 'Content-Type' => 'text/html'
  , data   => "<html></html>"
  );

Mail::Message->buildFromBody(BODY, [HEAD], HEADERS) Shape a message around a BODY. Bodies have information about their content in them, which is used to construct a header for the message. You may specify a HEAD object which is pre-initialized, or one is created for you (also when HEAD is CWundef). Next to that, more HEADERS can be specified which are stored in that header. Header fields are added in order, and before the header lines as defined by the body are taken. They may be supplied as key-value pairs or Mail::Message::Field objects. In case of a key-value pair, the field's name is to be used as key and the value is a string, address (Mail::Address object), or array of addresses. A CWDate, CWMessage-Id, and CWMIME-Version field are added unless supplied. Example: 

 my $type = Mail::Message::Field->new('Content-Type', 'text/html'
   , 'charset="us-ascii"');

 my @to   = ( Mail::Address->new('Your name', 'you@example.com')
            , 'world@example.info'
            );

 my $msg  = Mail::Message->buildFromBody
   ( $body
   , From => 'me@example.nl'
   , To   => \@to
   , $type
   );

DIAGNOSTICS

Error: Only build() Mail::Message's; they are not in a folder yet

You may wish to construct a message to be stored in a some kind of folder, but you need to do that in two steps. First, create a normal Mail::Message, and then add it to the folder. During this Mail::Box::addMessage() process, the message will get coerce()-d into the right message type, adding storage information and the like.

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 CWbuild method in MailBox is modelled after the CWbuild method as provided by MIMETools, but with a few simplifications:

When a keys starts with a capital, than it is always a header field
When a keys is lower-cased, it is always something else
You use the real field-names, not abbreviations
All field names are accepted
You may specify field objects between key-value pairs
A lot of facts are auto-detected, like content-type and encoding
You can create a multipart at once

Hum, reading the list above... what is equivalent? 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 CWContent-* 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 CWtext/plain body is constructed (MIME::Types does not find an extension on the filename so defaults to CWtext/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.

REFERENCES

See the MailBox website at <http://perl.overmeer.net/mailbox/> for more details.

COPYRIGHTS

Distribution version 2.063. Written by Mark Overmeer (mark@overmeer.net). 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.