Mail::Builder - Easily create plaintext/html e-mail messages with attachments, |
Mail::Builder - Easily create plaintext/html e-mail messages with attachments, inline images
use Mail::Builder; my $mail = Mail::Builder->new(); $mail->from('mightypirate@meele-island.mq','Guybrush Threepwood'); $mail->to->add('manuel.calavera@dod.mx','Manuel Calavera'); $mail->cc->add('glotis@dod.mx'); $mail->subject('Party at Sam\'s place'); $mail->htmltext('<h1>Party invitation</h1> ... '); $mail->attachment->add('direction_samandmax.pdf');
# Send it with your favourite module (e.g. Email::Send) my $mailer = Email::Send->new({mailer => 'Sendmail'})->send($mail->stringify); # Or mess with MIME::Entity objects my $mime = $mail->build_message;
This module helps you to build e-mails with attachments, inline images, multiple recipients, ... without having to worry about the underlying MIME stuff and encoding issues. Mail::Builder relies heavily on the the MIME::Entity manpage module from the the MIME::Tools manpage distribution.
The module will create the correct MIME bodies, headers and containers (multipart/mixed, multipart/related, multipart/alternative) depending on if you use attachments, HTML text and inline images.
Addresses, attachments and inline images are handled as objects by helper classes:
Stores an e-mail address and a display name.
This classes manages attachments which can be created either from files in the filesystem or from data in memory.
The Address: Mail::Builder::Image class manages images that should be displayed in the e-mail body.
Helper class for handling list of varoius items (recipient lists, attachment lists, ...)
This is a simple constructor. It does not expect any parameters.
Returns the e-mail message as a string. This string can be passed to modules like the Email::Send manpage.
This method is just a shortcut to $mb->build_message->stringify
Returns the e-mail message as a MIME::Entity object. You can mess arround with the object, change parts, ... as you wish.
Every time you call build_message the MIME::Entity object will be created, which can take some time if you are sending bulk e-mails. In order to increase the processing speed Mail::Builder::Attachment and Mail::Builder::Image entities will be cached and only rebuilt if something has changed.
These accessors set/return the from and reply address as well as the returnpath for bounced messages.
$obj->from(EMAIL[,NAME]) OR $obj->from(Mail::Builder::Address)
This accessor always returns a Mail::Builder::Address object.
To change the attribute value you can either supply a the Mail::Builder::Address manpage
object or scalar parameters which will be passed to
Mail::Builder::Address->new
. (email address, and an optional display
name)
$obj->to(Mail::Builder::List) OR $obj->to(Mail::Builder::Address) OR $obj->to(EMAIL[,NAME])
This accessor always returns a the Mail::Builder::List manpage object containing the Mail::Builder::Address manpage objects.
To alter the values you can either
Mail::Builder::Address->new
The the Mail::Builder::List manpage package provides some basic methods for manipulating the list of recipients. e.g.
$obj->to->add(EMAIL[,NAME]) OR $obj->to->add(Mail::Builder::Address)
e-mail text language
Message ID of the e-mail. Read only and available only after the
build_message
or stingify
methods have been called.
Accessor for the name of the senders organisation.
Priority accessor. Accepts values from 1 to 5. The default priority is 3.
e-mail subject accessor. Must be specified.
HTML mail body accessor.
Plaintext mail body accessor. This text will be autogenerated from htmltext if not provided by the user. Simple formating (e.g. <strong>, <em>) will be converted to pseudo formating.
The following html tags will be transformed:
Italic text will be surounded by underscores. (_italic text_)
Headlines will be replaced with two equal signs (== Headline)
Bold text will be marked by stars (*bold text*)
A horizontal rule is replaced with 60 dashes.
Single linebreak
Two linebreaks
Prints the alt text of the image if any.
Prints the link url surrounded by brackets ([http://myurl.com text])
All list items will be indented with a tab and prefixed with a start (*) or an index number.
Tables are converted into text using the Text::Table manpage.
$obj->attachment(Mail::Builder::List) OR $obj->attachment(Mail::Builder::Attachment) OR $obj->attachment(PATH[,NAME,MIME]) This accessor always returns a Mail::Builder::List object. If you supply a L<Mail::Builder::List> the list will be replaced.
If you pass a Mail::Builder::Attachment object or a scalar path (with an optional name an mime type) the current list will be reset and the new attachment will be added.
The the Mail::Builder::List manpage package provides some basic methods for manipulating the list of recipients.
If you want to append an additional attachment to the list use
$obj->attachment->add(PATH[,NAME,MIME]) OR $obj->attachment->add(Mail::Builder::Attachment)
$obj->image(Mail::Builder::List) OR $obj->image(Mail::Builder::Image) OR $obj->image(PATH[,ID]) This accessor always returns a Mail::Builder::List object. If you supply a L<Mail::Builder::List> the list will be replaced.
If you pass a Mail::Builder::Image object or a scalar path (with an optional id) the current list will be reset and the new image will be added.
The the Mail::Builder::List manpage package provides some basic methods for manipulating the list of recipients.
If you want to append an additional attachment to the list use
$obj->image->add(PATH[,ID]) OR $obj->image->add(Mail::Builder::Image)
You can embed the image into the html mail body code by referencing the ID. If you don't provide an ID the lowercase filename without the extension will be used as the ID.
<img src="cid:logo"/>
Only jpg, gif and png images may be added as inline images.
If you want to send multiple e-mail messages from one Mail::Builder object (e.g. a solicited mailing to multiple recipients) you have to pay special attention, or else you might end up with mixed contents and growing recipients lists.
# Example for a mass mailing foreach my $recipient (@recipients) { $mb->to->reset; # Remove all recipients $mb->to->add($recipient); # Add current recipuent # Alternatively you could use $mb->to($recipient); which has the # same effect as the two previous commands. Same goes for 'cc' and 'bcc' $mb->plaintext(undef); # Reset plaintext, otherwise it will not be autogenerated from htmltext $mb->htmltext(qq[<h1>Hello $recipient!</h1> Text, yadda yadda! ]); my $mail = $mb->stringify(); # Send $mail ,,, } From 1.10 on Mail::Builder only supports utf-8 charsets for mails. Supporting multiple encodings turned out to be error prone and not necessary since all modern mail clients support utf-8.
Please report any bugs or feature requests to
bug-mail-builder@rt.cpan.org
, or through the web interface at
http://rt.cpan.org. I will be notified, and then you'll automatically be
notified of progress on your bug as I make changes.
Maroš Kollár CPAN ID: MAROS maros [at] k-1.com http://www.k-1.com
Mail::Builder is Copyright (c) 2007,2008 Maroš Kollár.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself as long it is not used for sending unsolicited mail (SPAM):
"Thou shalt not send SPAM with this module."
The full text of the license can be found in the LICENSE file included with this module.
The the Mime::Entity manpage module in the the Mime::Tools manpage distribution.
Mail::Builder - Easily create plaintext/html e-mail messages with attachments, |