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

SYNOPSIS
     use Mail::Builder;

     my $mail = Mail::Builder->new();

     $mail->from('[email protected]','Guybrush Threepwood');
     $mail->to->add('[email protected]','Manuel Calavera');
     $mail->cc->add('[email protected]');
     $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;
     $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 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.

   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::File and
       Mail::Builder::Attachment::Data

       This classes manage attachments which can be created either from
       files in the filesystem 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 (recipient lists,
       attachment lists, image 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
    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.

 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])
    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 list object replaces the
       old one if the list types match

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

   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 sender's organisation. This header field is
   not part of the RFC 4021, however supported by many mailer applications.

  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.

  mailer
   Mailer name.

  plaintext
   Plaintext mail body accessor. 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 spam
   enginges rate 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.

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

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

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

        # Alternatively you could use $mb->to($recipient); which has the
        # same effect as the two previous commands. Same applies to 'cc' and 'bcc'

        $mb->plaintext(undef);
        # Reset plaintext, otherwise it will not be autogenerated from htmltext
        # after the first run

        $mb->htmltext(qq[<h1>Hello $recipient!</h1> Text, yadda yadda! ]);

        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.

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
   "[email protected]", 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

ACKNOWLEDGEMENTS
   This module was written for my old employer the Centre for Social
   Innovation <http://www.zsi.at> and is currently advanced by Revdev
   <http://www.revdev.at>, a nice litte software company I run with Koki
   and Domm (<http://search.cpan.org/~domm/>).

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.

   Furthermore these modules are bing used for various tasks:

   *   Email::Valid for validating e-mail addresses =item *
       HTML::TreeBuilder for parsing html and generating plaintext =item *
       MIME::Types for guessing attachment mime types =item *
       Email::MessageID for generating unique message IDs =item * Encode
       for encoding issues

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.