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:

    *   Mail::Builder::Address

        Stores an e-mail address and a display name.

    *   Attachments: Mail::Builder::Attachment

        This class manages attachments which can be created either from
        files in the filesystem, filehandles or from data in memory.

    *   Inline images:Mail::Builder::Image

        The Mail::Builder::Image class manages images that should be
        displayed in the html e-mail body. (<img src="cid:imageid" />)

    *   Mail::Builder::List

        Helper class for handling list of varoius items (i.e. recipient
        lists, attachment lists and image lists)

METHODS
  Constructors
   new
    This is a simple constructor. It accepts all defined acccessors as a
    Hash or 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 and
    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

    *   a Mail::Builder::Address object

    *   an Email::Address object

    *   a list containing an e-mail address and optionally name and comment

    *   a HashRef that will be passed to the Mail::Builder::Address
        constructor (Keys: email, name and comment)

    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

    *   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 list object replaces the
        old one if the list types matches.

    *   Scalar and HashRef values will be passed to
        "Mail::Builder::Address->new". The returned object will be added to
        the object list.

    *   Supply a Email::Address object. This will reset the current list,
        generate a Mail::Builder::Address object and add it to the list.

    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 "stringify" methods have
    been called. Each call to "build_message" or "stringify" 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:

    *   I, EM

        Italic text will be surrounded by underscores. (_italic text_)

    *   H1, H2, H3, ...

        Two equal signs are prepended to headlines (== 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.

   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:

    *   Email::Valid for validating e-mail addresses

    *   Email::MessageID for generating unique message IDs

    *   HTML::TreeBuilder for parsing html and generating plaintext

    *   MIME::Types for guessing attachment mime types