Mail::Message::Construct::Build - phpMan

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

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

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

     Mail::Message->build
       ( From     => 'me AT myhost.com'
       , To       => 'you AT yourhost.com'
       , Subject  => "Read our folder!"

       , data     => \@lines
       , file     => 'folder.pdf'
       )->send(via => 'postfix');

DESCRIPTION
    Complex functionality on Mail::Message objects is implemented in
    different files which are autoloaded. This file implements the building
    of messages from various simpler 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 "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 AT home.nl'
          , To      => Mail::Address->new('your name', 'you AT yourplace.aq')
          , Cc      => 'everyone AT 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>"
          );

    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 "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 AT example.com')
                    , 'world AT example.info'
                    );

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

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:

    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 AT myhost.com',
                                To       => 'you AT 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 AT myhost.com'
       , To       => 'you AT 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.

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.

SEE ALSO
    This module is part of Mail-Message distribution version 3.012, built on
    February 11, 2022. Website: http://perl.overmeer.net/CPAN/

LICENSE
    Copyrights 2001-2022 by [Mark Overmeer <markov AT cpan.org>]. For other
    contributors see ChangeLog.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself. See http://dev.perl.org/licenses/