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 <B>afterB> 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.
|Mail::Message-><B>buildFromBodyB>(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 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 fields 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.
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:
Hum, reading the list above... what is equivalent? MIME::Entity is not that simple after all! Lets look at an example from MIME::Entitys manual page:
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
### Create the top-level, and set up the mail headers: $top = MIME::Entity->build(Type => "multipart/mixed", From => firstname.lastname@example.org, To => email@example.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 well create with text we have on-hand: $top->attach(Data => $contents);
The MailBox equivalent could be
build, starting with nothing
buildFromBody, body becomes message
The Content-* fields
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.
Error: Only build() Mail::Messages; 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.
This module is part of Mail-Box distribution version 2.109, built on August 19, 2013. Website: http://perl.overmeer.net/mailbox/
Copyrights 2001-2013 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
|perl v5.20.3||MAIL::MESSAGE::CONSTRUCT::BUILD (3)||2013-08-19|