Message::Construct(3)

NAME
Mail::Message::Construct - extends the functionality of a Mail::Message

SYNOPSIS
 my $msg1 = Mail::Message->read(\*STDIN);
 my $msg2 = Mail::Message->read(\@lines);

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

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

 my Mail::Message $reply = $message->reply;
 my $quoted  = $message->replyPrelude($head->get('From'));

DESCRIPTION
Read "Mail::Box-Overview" and "Mail::Message" first.

When complex methods are called on a "Mail::Message"-object, this package is autoloaded to supply that functionality.

METHOD INDEX
The general methods for "Mail::Message::Construct" objects:

      bounce OPTIONS                       lines
      build [MESSAGE|BODY], CONTENT        printStructure [INDENT]
      buildFromBody BODY, HEADERS          read FILEHANDLE|SCALAR|REF-...
      file                                 reply OPTIONS
      forward OPTIONS                      replyPrelude [STRING|FIELD|...
      forwardPostlude                      replySubject STRING
      forwardPrelude                       string
      forwardSubject STRING

METHODS

read FILEHANDLE|SCALAR|REF-SCALAR|ARRAY-OF-LINES, OPTIONS
    (Class method) Read a message from a FILEHANDLE, SCALAR, a reference to a SCALAR, or an array of LINES. The OPTIONS are passed to the "new()" of the message which is created.

    Please have a look at "build" and "buildFromBody" in "Mail::Message::Construct" before thinking about this "read" method. Use this "read" only when you have a file-handle like STDIN to parse from, or some external source of message lines. When you already have a separate set of head and body lines, then "read" is certainly not your best choice.

    Examples:

     my $msg1 = Mail::Message->read(\*STDIN);
     my $msg2 = Mail::Message->read(\@lines, log => 'PROGRESS');
     $folder->addMessages($msg1, $msg2);

     my $msg3 = Mail::Message->read(<<MSG);
     Subject: hello world
     To: you@example.com
                          # warning: empty line required !!!
     Hi, greatings!
     MSG

reply OPTIONS
    Start a reply to this message. Some of the header-lines of the original message will be taken. A message-id will be assigned. Some header lines will be updated to facilitate message-thread detection (see "Mail::Box::Thread::Manager").

    You may reply to a whole message or a message part.

     OPTIONS         DESCRIBED IN              DEFAULT
     Bcc             Mail::Message::Construct  undef
     Cc              Mail::Message::Construct  <'cc' in current>
     From            Mail::Message::Construct  <'to' in current>
     Message-ID      Mail::Message::Construct  <uniquely generated>
     Subject         Mail::Message::Construct  <see replySubject>
     To              Mail::Message::Construct  <'from' in current>

     body            Mail::Message::Construct  undef
     group_reply     Mail::Message::Construct  1
     include         Mail::Message::Construct  'INLINE'
     message_type    Mail::Message::Construct  'Mail::Message'
     postlude        Mail::Message::Construct  undef
     prelude         Mail::Message::Construct  undef
     quote           Mail::Message::Construct  '=E<gt> '
     strip_signature Mail::Message::Construct  qr/^--\s/

    The OPTIONS are:

    * body => BODY
        Specifies the body of the message which is the reply. Adviced in other cases: prepare the body of the reply before the reply is called. It will avoid needless copying within "Mail::Message".

    * group_reply => BOOLEAN
        Will the people listed in the "Cc" headers (those who received the message where you reply to now) also receive this message as carbon copy?

    * include => 'NO'|'INLINE'|'ATTACH'
        Must the message where this is a reply to be included in the message? If 'NO' then not. With 'INLINE' a reply body is composed. 'ATTACH' will create a multi-part body, where the original message is added after the specified body. It is only possible to inline textual messages, therefore binary or multipart messages will always be inclosed as attachment.

    * message_type => CLASS
        Create a message with the requested type. By default, it will be a "Mail::Message". This is correct, because it will be coerced into the correct folder message type when it is added to that folder.

    * max_signature => INTEGER
        Passed to "stripSignature" on the body as parameter "max_lines". Only effective for single-part messages.

    * prelude => BODY|LINES
        The line(s) which will be added before the quoted reply lines. If nothing is specified, the result of the "replyPrelude()" method (as described below) is taken. When "undef" is specified, no prelude will be added.

    * postlude => BODY|LINES
        The line(s) which to be added after the quoted reply lines. Create a body for it first. This should not include the signature, which has its own option. The signature will be added after the postlude when the reply is INLINEd.

    * quote => CODE|STRING
        Mangle the lines of an "INLINE"d reply with CODE, or by prepending a STRING to each line. The routine specified by CODE is called when the line is in $_.

        By default, '> ' is added before each line. Specify "undef" to disable quoting. This option is processed after the body has been decoded.

    * signature => BODY|MESSAGE
        The signature to be added in case of a multi-part reply. The mime-type of the signature body should indicate this is a used as such. However, in INLINE mode, the body will be taken, a line containing '-- ' added before it, and added behind the epilogue.

    * strip_signature => REGEXP|STRING|CODE
        Remove the signature of the sender. The value of this paramter is passed to the body's "stripSignature" method (see "Mail::Message::Body") as "pattern" unless the source text is not included. The signature is stripped from the message before quoting.

        When a multipart body is encountered, and the message is included to ATTACH, the parts which look like signatures will be removed. If only one message remains, it will be the added as single attachment, otherwise a nested multipart will be the result. The value of this option does not matter, as long as it is present. See "Mail::Message::Body::Multipart".

    You may wish to overrule some of the default settings for the reply immediately (or you may do later with "set()" on the header). To overrule use

    * To => ADDRESSES
        The destination of your message, by default taken from the "Reply-To" field in the source message. If that field is not present, the "From" field is taken. The ADDRESSES may be specified as string, or a "Mail::Address" object, or as array of "Mail::Address" objects.

    * From => ADDRESSEj
        Your identification, by default taken from the "To" field of the source message.

    * Bcc => ADDRESSES
        Receivers of blind carbon copies: their names will not be published to other message receivers.

    * Cc => ADDRESSES
        The carbon-copy receivers, by default a copy of the "Cc" field of the source message.

    * Message-ID => STRING
        Supply a STRING as specific message-id for the reply. By default, one is generated for you. If there are no angles around your id, they will be added.

    * Subject => STRING|CODE
        Force the subject line to the specific STRING, or the result of the subroutine specified by CODE. The subroutine will be called passing the subject of the original message as only argument. By default, the "replySubject" method (described below) is used.

    Example:

      my $reply = $msg->reply
       ( prelude         => "No spam, please!\n\n"
       , postlude        => "\nGreetings\n"
       , strip_signature => 1
       , signature       => $my_pgp_key
       , group_reply     => 1
       );

replySubject STRING
    (Class or Instance method) Create a subject for a message which is a reply for this one. This routine tries to count the level of reply in subject field, and transform it into a standard form. Please contribute improvements.

      subject                 --> Re: subject
      Re: subject             --> Re[2]: subject
      Re[X]: subject          --> Re[X+1]: subject
      subject (Re)            --> Re[2]: subject
      subject (Forw)          --> Re[2]: subject
                              --> Re: your mail

replyPrelude [STRING|FIELD|ADDRESS]
    Produces a list of lines (usually only one), which will preceed the quoted body of the message. STRING must comply to the RFC822 email address specification, and is usually the content of a "To" or "From" header line. If a FIELD is specified, the field's body must be compliant. Without argument -or when the argument is "undef"- a slightly different line is produced.

    An characteristic example of the output is

      On Thu Oct 13 04:54:34 1995, him@example.com wrote:

forward OPTIONS
    Forward the content of this message. The body of the message to be forwarded is encapsulated in some accompanying text (if you have no wish for that, than "bounce" is your choice).

    You may forward a whole message, but also message parts.

     OPTIONS         DESCRIBED IN              DEFAULT
     Bcc             Mail::Message::Construct  undef
     Cc              Mail::Message::Construct  undef
     From            Mail::Message::Construct  <'to' in current>
     Message-ID      Mail::Message::Construct  <uniquely generated>
     Subject         Mail::Message::Construct  <see forwardSubject>
     To              Mail::Message::Construct  <obligatory>

     body            Mail::Message::Construct  undef
     include         Mail::Message::Construct  'INLINE'
     message_type    Mail::Message::Construct  'Mail::Message'
     postlude        Mail::Message::Construct  undef
     prelude         Mail::Message::Construct  undef
     quote           Mail::Message::Construct  undef
     strip_signature Mail::Message::Construct  qr/^--\s/

    The OPTIONS are:

    * include => 'INLINE'|'ATTACH'
        Must the message where this is a reply to be included in the message? With 'INLINE' a forward body is composed. 'ATTACH' will create a multi-part body, where the original message is added after the specified body. It is only possible to inline textual messages, therefore binary or multi-part messages will always be inclosed as attachment.

    * message_type => CLASS
        Create a message with the requested type. By default, it will be a "Mail::Message". This is correct, because it will be coerced into the correct folder message type when it is added to that folder.

    * max_signature => INTEGER
        Passed to "stripSignature" on the body as parameter "max_lines". Only effective for single-part messages.

    * prelude => BODY
        The line(s) which will be added before the quoted forwarded lines. If nothing is specified, the result of the "forwardPrelude()" method (as described below) is used. When "undef" is specified, no prelude will be added.

    * postlude => BODY
        The line(s) which to be added after the quoted reply lines. Create a body for it first. This should not include the signature, which has its own option. The signature will be added after the postlude when the forwarded message is INLINEd.

    * quote => CODE|STRING
        Mangle the lines of an "INLINE"d reply with CODE, or by prepending a STRING to each line. The routine specified by CODE is called when the line is in $_.

        By default, nothing is added before each line. This option is processed after the body has been decoded.

    * signature => BODY|MESSAGE
        The signature to be added in case of a multi-part forward. The mime-type of the signature body should indicate this is a used as such. However, in INLINE mode, the body will be taken, a line containing '-- ' added before it, and added behind the epilogue.

    * strip_signature => REGEXP|STRING|CODE
        Remove the signature of the sender. The value of this paramter is passed to the body's "stripSignature" method (see "Mail::Message::Body") as "pattern" unless the source text is not included. The signature is stripped from the message before quoting.

        When a multi-part body is encountered, and the message is included to ATTACH, the parts which look like signatures will be removed. If only one message remains, it will be the added as single attachment, otherwise a nested multipart will be the result. The value of this option does not matter, as long as it is present. See "Mail::Message::Body::Multipart".

    You may wish to overrule some of the default settings for the reply immediately (or you may do later with "set()" on the header). To overrule use

    * To => ADDRESSES
        The destination of your message. Obligatory. The ADDRESSES may be specified as string, a "Mail::Address" object, or as array of "Mail::Address" objects.

    * From => ADDRESSES
        Your identification, by default taken from the "To" field of the source message.

    * Bcc => ADDRESSES
        Receivers of blind carbon copies: their names will not be published to other message receivers.

    * Cc => ADDRESSES
        The carbon-copy receivers, by default noone.

    * Date => DATE
        The date to be used in the message sent.

    * Message-ID => STRING
        Supply a STRING as specific message-id for the reply. By default, one is generated for you. If there are no angles around your id, they will be added.

    * Subject => STRING|CODE
        Force the subject line to the specific STRING, or the result of the subroutine specified by CODE. The subroutine will be called passing the subject of the original message as only argument. By default, the "forwardSubject" method (described below) is used.

forwardSubject STRING
    Create a subject for a message which is a forward from this one. This routine tries to count the level of reply in subject field, and transform it into a standard form. Please contribute improvements.

      subject                 --> Forw: subject
      Re: subject             --> Forw: Re: subject
      Re[X]: subject          --> Forw: Re[X]: subject
                              --> Forwarded

forwardPrelude
    Create a few lines to be included before the forwarded message content. The return is an array of lines. Some example output is:

     ---- BEGIN forwarded message
     From: him@somewhere.else.nl (Original Sender)
     To: me@example.com (Me the receiver)
     Cc: the.rest@world.net
     Date: Wed, 9 Feb 2000 15:44:05 -0500
     <blank line>

forwardPostlude
    Added after the forwarded message. The output is:

     ---- END forwarded message

build [MESSAGE|BODY], CONTENT
    (Class method) 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. The keys which start with a capital are used as header-lines. Lowercased fields are used for other purposes as listed below. Each field may be used more than once.

    When the CONTENT reflects a header field to be, the key is used as name of the field (be careful with the capitisation). The value can be a string, an address ("Mail::Address" object), or a reference to an array of addresses.

    Special purpose keys (all other are header lines):

    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 the "data" options of "Mail::Message::Body::new()" 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                             # IO::Handle

    attach => BODY|MESSAGE|ARRAY-OF-BODY
        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

    If more than one "data", "file", and "attach" is specified, a multi-parted message 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'

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

buildFromBody BODY, HEADERS
    (Class method) Shape a message around a BODY. Bodies have information about their content in them, which is used to construct a header for the message. Next to that, more HEADERS can be specified.

    Header fields are added in order, and before the header lines as defined by the body are taken. They may be spullied 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.

    The "To" and "From" fields must be specified. A "Date" field is 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
       );

bounce OPTIONS
    Bounce the message off to a difference destination, or multiple destinations. Most OPTIONS specify header lines which are added to the original message. Their name will therefor be prepended by "Resent-". These lines have preference over the lines which do not start with "Resent-".

    Possible OPTIONS are

    * From => ADDRESS
        Your address as string or "Mail::Address" object.

    * To => ADDRESSES
        One or more destination addresses, as string, one "Mail::Address" object or array of "Mail::Address" objects.

    * Cc => ADDRESSES
        The receiver(s) of carbon-copies: not the main targets, but receiving an informational copy.

    * Bcc => ADDRESSES
        The receiver(s) of blind carbon-copies: the other receivers will not see these addresses.

    * Date => STRING
        A properly formatted STRING for the date. If not specified, the current time is used.

    * 'Message-ID' => KEY
        A unique KEY which identifies this message. If you do not specify a key, one is chosen for you. There is one "Resent-Message-ID" which identifies all bounces for this message. If one id is already present, than this option will be ignored.

    * 'Reply-To' => ADDRESS
        The address where the receiver has to reply to.

    Examples:

     my $bounce = $folder->message(3)->bounce(To => 'you', Bcc => 'everyone');
     $bounce->send;
     $outbox->addMessage($bounce);

printStructure [INDENT]
    Print the structure of a message, which is primarily useful for debugging purposes.

string
    Returns the whole message as string.

lines
    Returns the whole message as set of lines.

file
    Returns the message as file-handle.

SEE ALSO
Mail::Box-Overview

For support and additional documentation, see http://perl.overmeer.net/mailbox/

AUTHOR
Mark Overmeer (mailbox@overmeer.net). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION
This code is beta, version 2.018.

Copyright (c) 2001-2002 Mark Overmeer. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.