my $msg1 = Mail::Message->build ( From => 'me', data => "only two\nlines\n"); my $msg2 = Mail::Message->buildFromBody($body); Mail::Message->build ( From => 'me@myhost.com' , To => 'you@yourhost.com' , Subject => "Read our folder!" , data => \@lines , file => 'folder.pdf' )->send(via => 'postfix');
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 => $folder->message(3)->decoded # body attach => $folder->message(3) # message attach => [ $msg1, $msg2->part(6), $msg3->body ];
data => [ "line 1\n", "line 2\n" ] # array of lines data => <<'TEXT' # string line 1 line 2 TEXT
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
example:
my $msg = Mail::Message->build ( From => 'me@home.nl' , To => Mail::Address->new('your name', 'you@yourplace.aq') , Cc => 'everyone@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>" );
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
);
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! 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.
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/