Maroš Kollár > Mail-Builder > Mail::Builder

Download:
Mail-Builder-2.09.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 2.09   Source  

NAME ^

Mail::Builder - Easily create plaintext/html e-mail messages with attachments and inline images

SYNOPSIS ^

  use Mail::Builder;
  
  my $mail = Mail::Builder->new({
      subject   => 'Party at Sam\'s place',
      from      => 'mightypirate@meele-island.mq',
      htmltext  => '<h1>Party invitation</h1> ... ',
      attachment=> '/path/to/direction_samandmax.pdf',
  });
  
  # Alter from name
  $mail->from->name('Guybrush Threepwood');
  # Set recipent
  $mail->to('manuel.calavera@dod.mx','Manuel Calavera');
  # Add one more recipient
  $mail->to->add('glotis@dod.mx');
  
  # 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;
  $mime-> ....

DESCRIPTION ^

This module helps you to build correct e-mails with attachments, inline images, multiple recipients, ... without having to worry about the underlying MIME and encoding issues. Mail::Builder relies heavily on the MIME::Entity module from the MIME::Tools 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.

Furthermore it will encode non-ascii header data and autogenerate plaintext messages (if you don't provide it yourself or disable the autotext option) from html content.

Addresses, attachments and inline images are handled as objects by helper classes:

METHODS ^

Constructors

new

This is a simple constructor. It accepts all defined acccessors as a Hash orr HashRef.

Public methods

stringify

Returns the e-mail message as a string. This string can be passed to modules like Email::Send.

This method is just a shortcut to $mb->build_message->stringify

build_message

 my $entity = $mb->build_message();
 
 # Print the entire message:
 $entity->print(\*STDOUT);
 
 # Stringify the entire message:
 print $entity->stringify; 

Returns the e-mail message as a MIME::Entity object. You can mess around 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.

Each call to this method also changes the messageid.

purge_cache

Emptys the attachment and image cache and removes the plaintext text if it has been autogenerated from html text. Also resets the Message ID nd date header.

Accessors

from, returnpath, reply, sender

These accessors set/return the from, sender and reply address as well as the returnpath for bounced messages.

 $obj->from(EMAIL[,NAME[,COMMENT]])
 OR
 $obj->from(Mail::Builder::Address)
 OR
 $obj->from(Email::Address)
 OR
 $obj->from({
     email      => EMAIL,
     [name      => NAME,]
     [comment   => COMMENT,]
 });

This accessor always returns a Mail::Builder::Address object.

To change the attribute value you can either supply

The presence of a value can be checked with the has_from, has_reply, has_reply and has_sender methods.

Values can be cleared with the clear_from, clear_reply, clear_reply and clear_sender methods.

Email::Valid options may be changed by setting the appropriate values in the %Mail::Builder::TypeConstraints::EMAILVALID hash.

Eg. if you want to disable the check for valid TLDs you can set the 'tldcheck' option (without dashes 'tldcheck' and not '-tldcheck'):

 $Mail::Builder::TypeConstraints::EMAILVALID{tldcheck} = 0;

to, cc, bcc

 $obj->to(Mail::Builder::List)
 OR
 $obj->to(Mail::Builder::Address)
 OR
 $obj->to(Email::Address)
 OR
 $obj->to(EMAIL[,NAME[,COMMENT]])
 OR
 $obj->to({
     email      => EMAIL,
     [name      => NAME,]
     [comment   => COMMENT,]
 })
 OR
 $obj->to([ 
    Mail::Builder::Address | Email::Address | HashRef | EMAIL
 ])

This accessor always returns a Mail::Builder::List object containing Mail::Builder::Address objects.

To alter the values you can either

The Mail::Builder::List package provides some basic methods for manipulating the list of recipients. e.g.

 $obj->to->add(EMAIL[,NAME[,COMMENT]])
 OR
 $obj->to->add(Mail::Builder::Address)
 OR
 $obj->to->add(Email::Address)

date

e-mail date header. Accepts/returns a RFC2822 date string. Also accepts a DateTime object or epoch integer. Will be autogenerated if not provided. clear_date can be used to reset the date accessor.

language

e-mail text language. Additionally the has_language and clear_language methods can be used to check respectively clear the value.

messageid

Message ID of the e-mail as a Email::MessageID object. Read only and available only after the build_message or stingify methods have been called. Each call to build_message or stingify changes the message ID. The has_messageid and clear_messageid methods can be used to check respectively clear the value.

organization

Accessor for the name of the sender's organisation. This header field is not part of the RFC 4021, however supported by many mailer applications. Additionally the has_organization and clear_organization methods can be used to check or clear the value.

priority

Priority accessor. Accepts values from 1 to 5. The default priority is 3.

subject

e-mail subject accessor. Must be specified.

htmltext

HTML mail body accessor. Additionally the has_htmltext and clear_htmltext methods can be used to check or clear the value.

mailer

Mailer name.

plaintext

Plaintext mail body accessor. The clear_plaintext and has_plaintext methods can be used to check or clear the value.

This text will be autogenerated from htmltext if not provided by the user and the autotext option is not turned off. Simple formating (e.g. <strong>, <em>, ...) will be converted to pseudo formating.

If you want to disable the autogeneration of plaintext parts set the autotext accessor to a false value. However be aware that most anti-spam enginges tag html e-mail messages without a plaintext part as spam.

The following html tags will be transformed to simple markup:

autotext

Enables the autogeneration of plaintext parts from HTML.

Default TRUE.

attachment

 $obj->attachment(Mail::Builder::List)
 OR
 $obj->attachment(Mail::Builder::Attachment)
 OR
 $obj->attachment(PATH | Path::Class::File | FH | IO::File | SCALARREF)
 OR
 $obj->attachment({
     file       => PATH | Path::Class::File | FH | IO::File | SCALARREF,
     [name      => NAME,]
     [mimetype  => MIME,]
 })
 OR
 $obj->attachment([
    HashRef | Mail::Builder::Attachment | PATH | Path::Class::File | FH | IO::File | SCALARREF
 ]);

This accessor always returns a Mail::Builder::List object. If you supply a Mail::Builder::List the list will be replaced.

If you pass a Mail::Builder::Attachment object, a filehandle, an IO::File object, a Path::Class::File object, a path or a scalar reference or a scalar path the current list will be reset and the new attachment will be added.

The Mail::Builder::List package provides some basic methods for manipulating the list of attachments.

If you want to append an additional attachment to the list use

 $obj->attachment->add(PATH | Path::Class::File | FH | IO::File | ScalarRef)
 OR
 $obj->attachment->add({
     file       => PATH | Path::Class::File | FH | IO::File | ScalarRef,
     [name      => NAME,]
     [mimetype  => MIME,]
 })
 OR
 $obj->attachment->add(Mail::Builder::Attachment)

image

 $obj->image(Mail::Builder::List)
 OR
 $obj->image(Mail::Builder::Image)
 OR
 $obj->image(PATH | Path::Class::File | FH | IO::File | ScalarRef)
 OR
 $obj->image({
     file       => PATH | Path::Class::File | FH | IO::File | ScalarRef,
     [id        => ID,]
     [mimetype  => MIME,]
 })
 OR
 $obj->image([
    HashRef | Mail::Builder::Image | PATH | Path::Class::File | FH | IO::File | ScalarRef
 ]);

This accessor always returns a Mail::Builder::List object. If you supply a 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 Mail::Builder::List package provides some basic methods for manipulating the list of inline images.

If you want to append an additional attachment to the list use

 $obj->image->add(PATH | Path::Class::File | FH | IO::File | ScalarRef)
 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 file extension will be used as the ID.

 <img src="cid:logo"/>

Only jpg, gif and png images may be added as inline images.

EXAMPLE ^

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 growing recipients lists.

 # Example for a mass mailing
 foreach my $recipient (@recipients) {
     $mb->to->reset; # Remove all recipients
     $mb->to->add($recipient); # Add current recipient
     
     # Alternatively you could use $mb->to($recipient); which has the
     # same effect as the two previous commands. Same applies to 'cc' and 'bcc'
     
     # Autogenerated Plaintext will be reset
     $mb->htmltext(qq[<h1>Hello $recipient!</h1> Text, yadda yadda! ]);
     
     # Plaintext is autogenerated
     my $mail = $mb->stringify();
     
     # Send $mail ... 
 }

IMPORTANT CHANGES ^

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.

Starting with Mail::Builder 2.0 the Mail::Builder::Attachment::* and Mail::Builder::Image::* classes have been deprecated. Use the base classes Mail::Builder::Attachment and Mail::Builder::Image instead.

CAVEATS ^

Watch out when sending Mail::Builder generated mails with Email::Send::SMTP: The 'Return-Path' headers are ignored by the MTA since Email::Send::SMTP uses the 'From' header for SMTP handshake. Postfix (any maybe some other MTAs) overwrites the 'Return-Path' field in the data with the e-mail used in the handshake ('From'). The behaviour of Email::Send::SMTP may however be modified by replacing the get_env_sender and get_env_recipients methods. See Email::Send::SMTP for more details.

SUPPORT ^

Please report any bugs or feature requests to bug-mail-builder@rt.cpan.org, or through the web interface at http://rt.cpan.org/Public/Bug/Report.html?Queue=Mail::Builder. I will be notified, and then you'll automatically be notified of progress on your report as I make changes.

AUTHOR ^

    Maroš Kollár
    CPAN ID: MAROS
    maros [at] k-1.com
    http://www.k-1.com

COPYRIGHT ^

Mail::Builder is Copyright (c) 2007-2010 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.

SEE ALSO ^

The Mime::Entity module in the Mime::Tools distribution.

Mail::Builder::Simple provides a wrapper around this module and itegrates it with Email::Sender::Simple

Furthermore these modules are being used for various tasks:

syntax highlighting: