METHODS

Constructing a message

$class->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 undef are ignored.

If more than one data, file, and attach is specified, a multi-parted message is created. Some Content-* 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 multipart/alternative in stead of the default multipart/mixed. If you wish to specify the type per datum, you need to start playing with Mail::Message::Body objects yourself.

This build method will use buildFromBody() when the body object has been constructed. Together, they produce your message.

Option Default

attach

undef

data

undef

file

undef

files

[ ]

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 message/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|ARRAY
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. [2.119] You may even pass more than one file at once: 'file' and 'files' option are equivalent.
 my $in = IO::File->new('/etc/passwd', 'r');

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

 open my $in, '<:raw', '/etc/passwd';    # alternative for IO::File
files => ARRAY-OF-FILE
Alias for option file.
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'
  , Subject => "Let's talk",
  , $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>"
  );
» 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.

$class->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 undef). 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 Date, Message-Id, and MIME-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
   );