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 "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
- 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 "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
);
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@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 "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-Box distribution version 2.105, built on May 07,
2012. Website:
http://perl.overmeer.net/mailbox/
LICENSE¶
Copyrights 2001-2012 by [Mark Overmeer]. 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://www.perl.com/perl/misc/Artistic.html