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

SYNOPSIS
      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; 

DESCRIPTION
    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
    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.

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

    * Mail::Builder::Address
        Stores an e-mail address and a display name.

    * Attachments: Mail::Builder::Attachment::File and
    Mail::Builder::Attachment::Data
        This classes manages attachments which can be created either from
        files in the filesystem or from data in memory.

    * Inline images:Mail::Builder::Image
        The Address: Mail::Builder::Image class manages images that should
        be displayed in the e-mail body.

    * Mail::Builder::List
        Helper class for handling list of varoius items (recipient lists,
        attachment lists, ...)

METHODS
  Constructors
   new
    This is a simple constructor. It does not expect any parameters.

  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
    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.

  Accessors
   from, returnpath, reply
    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
    Mail::Builder::Address object or scalar parameters which will be passed
    to "Mail::Builder::Address->new". (email address, and an optional
    display name)

   charset (DEPRECATED)
   to, cc, bcc
     $obj->to(Mail::Builder::List)
     OR
     $obj->to(Mail::Builder::Address)
     OR
     $obj->to(EMAIL[,NAME])

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

    To alter the values you can either

    * Manipulate the Mail::Builder::List object (add, remove, ...)
    * Supply a Mail::Builder::Address object. This will reset the current
    list and add the object to the list.
    * Supply a Mail::Builder::List object. The object replaces the old one.
    * Scalar values will be passed to "Mail::Builder::Address->new"

    The Mail::Builder::List 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)

   language
    e-mail text language

   messageid
    Message ID of the e-mail. Read only and available only after the
    "build_message" or "stingify" methods have been called.

   organization
    Accessor for the name of the senders organisation.

   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.

   plaintext
    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:

    * I, EM
        Italic text will be surounded by underscores. (_italic text_)

    * H1, H2, H3, ...
        Headlines will be replaced with two equal signs (== Headline)

    * STRONG, B
        Bold text will be marked by stars (*bold text*)

    * HR
        A horizontal rule is replaced with 60 dashes.

    * BR
        Single linebreak

    * P, DIV
        Two linebreaks

    * IMG
        Prints the alt text of the image if any.

    * A Prints the link url surrounded by brackets ([http://myurl.com text])

    * UL, OL
        All list items will be indented with a tab and prefixed with a start
        (*) or an index number.

    * TABLE, TR, TD, TH
        Tables are converted into text using Text::Table.

   attachment
     $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 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 Mail::Builder::List 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)

   image
     $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 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 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.

CAVEATS
    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.

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>. I will be notified, and then you'll automatically
    be notified of progress on your bug 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,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.

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

