
=head1 NAME

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



=head1 SYNOPSIS

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

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


=head1 DESCRIPTION

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



=head1 METHODS


=head2 Constructing a message


Mail::Message-E<gt>B<build>([MESSAGE|BODY], CONTENT)

=over 4

Simplified message object builder.  In case a MESSAGE 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 C<undef> are ignored.

If more than one C<data>, C<file>, and C<attach> is specified, a multi-parted
message is created.  The C<Content-Type> field is treated separately: to
set the type of the produced message body after it has been created.  For
instance, to explicitly state that you wish a C<multipart/alternative>
in stead of the default C<multipart/mixed>.  If
you wish to specify the type per datum, you need to start playing with
L<Mail::Message::Body|Mail::Message::Body> objects yourself.

This C<build> method will use L<buildFromBody()|Mail::Message::Construct::Build/"Constructing a message"> 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|MESSAGE|ARRAY-OF-BODY

=over 4

One attachment to the message.  Each attachment can be full MESSAGE or a BODY.

 attach => $folder->message(3)->decoded  # body
 attach => $folder->message(3)           # message

=back

. data STRING|ARRAY-OF-LINES

=over 4

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 L<Mail::Message::Body::new(data)|Mail::Message::Body/"Constructors"> to
construct one.

  data => [ "line 1\n", "line 2\n" ]     # array of lines
  data => <<'TEXT'                       # string
 line 1
 line 2
 TEXT

=back

. file FILENAME|FILEHANDLE|IOHANDLE

=over 4

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

=back

. files ARRAY-OF-FILE

=over 4

See option file, but then an array reference collection more of them.

=back

. head HEAD

=over 4

Start with a prepared header, otherwise one is created.

=back

I<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>"
  );

=back

Mail::Message-E<gt>B<buildFromBody>(BODY, [HEAD], HEADERS)

=over 4

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 C<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 L<Mail::Message::Field|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 C<Date>, C<Message-Id>, and C<MIME-Version> field are added unless
supplied.

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

=back








=head1 REFERENCES

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

=head1 COPYRIGHTS

Distribution version 2.055.
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.


