NAME
    Mail::Builder::Simple - Send UTF-8 HTML and text email with attachments
    and inline images, eventually using templates

SYNOPSIS
     # Send a plain text email with Sendmail:

     use Mail::Builder::Simple;

     my $mail = Mail::Builder::Simple->new;

     $mail->send(
      from => 'me@host.com',
      to => 'you@yourhost.com',
      subject => 'The subject with UTF-8 chars',
      plaintext => "Hello,\n\nHow are you?\n",
     );

     # Send the email with an SMTP server:

     $mail->send(
      mail_client => {
       mailer => 'SMTP',
       mailer_args => [Host => 'smtp.host.com'],
      },
      from => 'me@host.com',
      to => 'you@yourhost.com',
      subject => 'The subject with UTF-8 chars',
      plaintext => "Hello,\n\nHow are you?\n",
     );

     # Send a text and HTML email with an attachment and an inline image
     # Specify the displayed name for To: and From: fields and add other headers

     $mail->send(
      from => ['me@host.com', 'My Name'],
      to => ['you@yourhost.com', 'Your Name'],
      reply => 'foo@anotherhost.com',
      subject => 'The subject with UTF-8 chars',
      plaintext => "Hello,\n\nHow are you?\n\n",
      htmltext => "<h1>Hello,</h1> <p>How are you?</p>",
      attachment => 'file.pdf',
      image => 'logo.png',
      priority => 1,
      mailer => 'My Mailer 0.01',
     );

DESCRIPTION
    "Mail::Builder::Simple" can create email messages with Mail::Builder and
    send them with Email::Send. It has the following features:

    UTF-8 encoding
        "Mail::Builder::Simple" automaticly encodes the body and headers of
        the email messages to UTF-8, so they can display the special chars
        in other languages than English correctly.

    attachments
        "Mail::Builder::Simple" allow adding one or more attachments to the
        message, without needing to specify their Content-Type if you don't
        want to.

        The attachments can be files saved on the disk or can be created on
        the fly, eventually using templates.

    images
        "Mail::Builder::Simple" can add inline images that will be displayed
        in the HTML part of the message.

    templates
        The body and the attachments can be created using a template, either
        using external template files or templates from scalar variables.

        "Mail::Builder::Simple" uses other modules like
        Mail::Builder::Simple::TT and Mail::Builder::Simple::HTML::Template
        in order to allow using Template or HTML::Template templates.

        For using another templating system, you can create a module like
        these 2 modules.

    mail sender
        "Mail::Builder::Simple" can send the email messages using any of the
        mailers allowed by Email::Send and some of them are: Sendmail,
        Qmail, SMTP, Gmail, NNTP.

        Some of these mailers might not be offered by the Email::Send main
        distribution, and you might need to install separate modules from
        CPAN (Such an example is Email::Send::Gmail.)

    configuration file
        All the parameters that can be sent to the "new()" function can be
        also stored in a configuration file, and this file can be used in
        more applications.

        For example, you could save the mailer type, the mailer host,
        username and password and maybe the "From:" field in a configuration
        file, so you won't need to specify them each time when you want to
        send an email.

Functions
    Mail::Builder::Simple offers the following functions:

    new()
        This is the constructor of the "Mail::Builder::Simple" object. This
        object is a Mail::Builder object also, so you can use the methods
        from Mail::Builder on it if you want.

    send()
        This function sends the email. After sending the email, it cleans
        the "To:", "CC:" and "BCC:" fields, so you can send the already
        built message to somebody else if you want, needing to specify only
        the recipient's email address.

    These 2 functions can receive a hash with parameters which have the keys
    explained below.

Parameters
  mail_client
    This parameter is optional.

    It is a hashref with all the options needed to configure Email::Send for
    sending the email messages.

    It looks like:

     mail_client => {
      mailer => 'SMTP',
      mailer_args => [Host => 'smtp.host.com'],
     },

    where the mailer can be 'SMTP', 'Sendmail', 'Qmail', 'Gmail', 'NNTP', or
    other types supported by Email::Send.

    "mailer_args" receives all the configuration options that might be
    required by the specified mailer.

    For example, for sending email with an SMTP host that require
    authentication, you should use:

     mailer_args => {
      mailer => 'SMTP',
      mailer_args => [
       Host => 'smtp.host.com',
       username => 'the_user',
       password => 'the_password',
      ],
     },

    If the parameter "mail_client" is not specified, the default mailer that
    is used is sendmail.

  template_args
    This parameter is optional.

    It is a hashref with all the arguments neede by the templating system
    you are using for creating the email body or the attachments.

    "template_args" can receive any kind of parameters, depending on the
    parameters which are accepted by the templating system used.
    "Mail::Builder::Simple" allows using more templating systems even for
    creating a single email message. If more templating systems are used to
    create an email message, all the templates will use the arguments from
    the hashref "template_args" unless overwritten, as you will see.

    It could look like:

     template_args => {
      INCLUDE_PATH => '/path/to/templates', #default "."
      ENCODING => 'UTF-8', #The default is UTF-8 anyway
     },

  template_vars
    This parameter is optional.

    It is a hashref with the pairs of variables from the templates and their
    values.

    An example:

     template_vars => {
      name => 'Gil Bates',
      preferences => ['pizza', 'yogurt', 'blondes'],
     },

    The variables from "template_vars" will be used by all the templates
    which are used for creating the email message, unless some of them are
    overwritten as you will see.

  email message fields
    These are the fields that create the email message. They are: "from, to,
    cc, bcc, subject, plaintext, htmltext, attachment, image, priority,
    reply, organization, returnpath, sender, language, mailer".

    There are many ways of using these fields, and I will explain them
    below.

  config_file
    This parameter is optional.

    It shows the path to a configuration file that holds some parameters you
    don't want to specify in each program.

    The configuration file can be any type of file supported by Config::Any:
    Apache config style (Config::General), JSON, INI files, XML, YAML or
    perl code.

    Here is an example of a configuration file that uses Config::General:
    (/home/user/email.conf)

     <mail_client>
      mailer SMTP
      <mailer_args>
       Host smtp.host.com
       username user
       password passwd
      </mailer_args>
     </mail_client>
     from user@host.com

    This configuration file contains options not only for the mailer, but it
    also contains the message field "From:" which wouldn't need to be
    specified when sending an email.

    Here is a program that sends an email using this configuration file:

     use Mail::Builder::Simple;

     my $mail = Mail::Builder::Simple->new(config_file => '/home/user/email.conf');

     $mail->send(
      to => 'you@yourhost.com',
      subject => 'The subject',
      htmltext => '<h1>Hello</h1> How are you?',
     );

    As all other parameters shown until now, "config_file" can be sent to
    both "new()" and "send()" functions.

  other email message headers
    You might need to include in your message some headers which are not in
    the list shown above. You can also add them as separate parameters, but
    they need to be capitalised exactly how they should appear in the email
    message.

    These headers overwrite the previous set headers that have the same name
    and they can be sent as parameters only to the "send()" method, not to
    the new().

    Here is an example of including the header "X-My-Special-Header":

     $mail->send(
      to => 'you@yourhost.com',
      subject => 'The subject',
      plaintext => 'The body',
      'X-My-Special-Header' => 'This is my header',
     );

Using the email message fields
  to, cc, bcc
    Here are a few ways of using the "To:" field:

    As parameters to the "new()" or "send()" functions:

    Set a single email address for the "To:" field:

     to => 'you@host.com',

    Set a single address and set the name that should be displayed in the
    "To:" field:

     to => ['you@host.com', 'Your Name - with UTF-8 chars'],

    Set more email addresses for the "To:" field in 2 ways:

     to => ['MORE', 'you@host.com', 'he@host2.com', 'she@host3.com'],
     or
     to => [['you@host.com'], ['he@host2.com'], ['she@host3.com']],

    Set more email addresses for the "To:" field, and also set the names
    that should be displayed:

     to => [['you@host.com', 'Your Name'], ['he@host2.com', 'His Name']],

    or as a method to the "Mail::Builder::Simple" object:

    Set an email address for the "To:" field:

     $mail->to('you@host.com');

    Set an email address for the "To:" field, and also set the name which is
    displayed:

     $mail->to('you@host.com', 'Your Name');

    Add the email address and the name which is displayed in the "To:"
    field. You can repeat this for more times.

     $mail->to->add('you@host.com');
     $mail->to->add('he@host2.com', 'His Name');

    You can set the "CC:" or "BCC:" fields of the message in the same way.

  from
    The "From:" field can be set using:

     from => 'me@myhost.com',
     or
     from => ['me@myhost.com', 'My Name'],
     or
     $mail->from('me@myhost.com');
     or
     $mail->from('me@myhost.com', 'My Name');

  subject
    You can specify the subject field as:

     subject => 'The subject',
     or
     $mail->subject('The subject');

  plaintext, htmltext
    "Mail::Builder::Simple" can create a plain-text message if you provide
    just the plaintext part, or a multipart message if you offer the
    htmltext also. You can even provide just the htmltext, and it will
    create the plaintext part automaticly.

    You can create the body of the message using:

     plaintext => "Hello,\n\nHow are you?",
     htmltext => "<h1>Hello,</h1> <p>How are you?</p>",

  attachments
    The attachments can be added as parameters to "new()" and "send()"
    methods.

    Attach a file without specifying an alternative name and its
    Content-Type:

     attachment => 'file.pdf',

    Attach a file specifying an alternative name and its Content-Type:

     attachment => ['/path/to/file', 'filename.pdf', 'application/pdf'],

    Attach more file without specifying alternative names and Content-Type
    in 2 ways:

     attachment => ['MORE', 'file1.pdf', 'file2.doc'],
     or
     attachment => [['file1.pdf'], ['file2.doc'], ['file3.html']],

    Attach more files specifying their alternative names and Content-Type:

     attachment => [
      ['file1', 'file1.pdf', 'application/pdf'],
      ['file2', 'file2.pdf', 'application/pdf'],
     ],

    or attach files using methods of the "Mail::Builder::Simple" object. You
    can repeat this for more times:

     $mail->attachment->add('file1.pdf');
     or
     $mail->attachment->add('file', 'file.pdf', 'application/pdf');

  images
    "Mail::Builder::Simple" allows attaching inline images that won't appear
    as attachments, but they will be displayed in the HTML part of the mail
    message.

    You can add them as parameters to the "new()" or "send()" functions.

    Add an inline image without specifying an alternative ID:

     image => 'image.png',

    Add an inline image and specify an alternative ID:

     image => ['/path/to/image.png', 'image_id'],

    Add more inline images without specifying an alternative ID:

     image => ['MORE', 'image1.png', 'image2.gif', 'image3.jpg'],
     or
    image => [['image1.png'], ['image2.gif'], ['image3.gif']],

    Add more inline images specifying an alternative ID:

     image => [
      ['/path/to/image1.png', 'logo'],
      ['image2.gif', 'img'],
      ['image3.jpg', 'picture'],
     ],

    or you can add them using methods of the "Mail::Builder::Simple" object.
    You can repeat it for more times:

     $mail->image->add('image.png');
     or
     $mail->image->add('/path/to/image.png', 'logo');

    Only the .png, .jpg and .gif images can be attached as inline images.

    The ID of the image is used for displaying the image in the HTML part of
    the email message, using something like the following HTML element for
    the "logo" ID:

     <img src="cid:logo" alt="logo">

    If you don't provide an ID, one is automaticly generated and it will be
    the lowercase of the file name of the images, without the extension.

Using templates
    "Mail::Builder::Simple" allows to create the text and HTML body of the
    email message or the attachments using templates.

    When the value of the parameters "plaintext", "htmltext" and
    "attachment" is an arrayref and the last element of that arrayref begins
    with ":", it means that this field is created using a template. The type
    of template is specified in that last element of the array.

  Types of templates
    "Mail::Builder::Simple" uses other plugin modules like
    Mail::Builder::Simple::TT and Mail::Builder::Simple::HTML::Template for
    creating the content using Template or HTML::Template.

    If you want to create the content using a templating system for which
    there isn't a plugin created yet, you can create that plugin. It is
    pretty simple.

    The templates that can be used for the moment are:

     Scalar
     TT
     TT-scalar
     HTML::Template
     HTML::Template-scalar

    Here are a few examples for creating a message plain text body using
    templates:

     # Create the plain text part of the email message using the TT template file "template.tt"
     
 my $mail = Mail::Builder::Simple->new;
     $mail->send(
      from => 'me@myhost.com',
      to => 'you@host.com',
      subject => 'The subject',
      plaintext => ['template.tt', ':TT'],
      template_args => {
       INCLUDE_PATH => '/path/to/templates',
      },
      template_vars => {
       name => 'My Name',
       age => 20,
      },
     );

    and the template file in /path/to/templates/template.tt could contain:

     Hello [% name %],
     My age is [% age %].

     # Create the plain text part of the email message using a TT template from a scalar variable
     
 my $template = <<EOF;
     Hello [% name %],
     My age is [% age %].
     EOF

     my $mail = Mail::Builder::Simple->new;
     $mail->send(
      from => 'me@myhost.com',
      to => 'you@host.com',
      subject => 'The subject',
      plaintext => [$template, ':TT-scalar'],
      template_vars => {
       name => 'My Name',
       age => 20,
      },
     );

     # Create the plain text part of the email message using L<HTML::Template> from a template file:

     plaintext => ['template.tmpl', ':HTML::Template'],

     # Create the plain text part of the email message using L<HTML::Template> from a template from a scalar variable

     plaintext => [$template_content, ':HTML::Template-scalar'],

    The HTML part of the email message can be created in exactly the same
    way.

      # Add an attachment created from a template file using TT:
      
   attachment => ['template.tt', 'generated_file_name.html', 'text/html', ':TT'],
       
 # Add an attachment created from a TT template from a scalar variable:
     
  attachment => [$template_content, 'generated_file_name.txt', 'text/plain', ':TT-scalar'],
      
 # Add an attachment created from a template file using L<HTML::Template>:
     
  attachment => ['template.tmpl', 'generated_file_name.txt', 'text/plain', ':HTML::Template'],
      
  # Add an attachment created from a template from a scalar variable using L<HTML::Template>:
      
   attachment => [$template_content, 'generated_file_name.html', 'text/html', ':HTML::Template-scalar'],

     # Add an attachment from a scalar variable, without using any templating system:
     
  attachment => [$file_content, 'generated_file_name.html', 'text/html', ':Scalar'],

    Using the ":Scalar" as the last element of the arrayref makes it
    possible to create any type of file on the fly and add it as attachment
    to an email message. You can also add any type of file using templates,
    if the templating system used can create the type of file you want to
    add.

  Advanced use of templates
    If an email message should be created using more than a single
    templating system, all the templates can share the arguments from the
    "template_args" hashref. For example if both Template and HTML::Template
    are used and we want to specify the path to the directory with
    templates, the "template_args" parameter could include:

     template_args => {
      INCLUDE_PATH => '/path/to/TT/templates',
        path => '/path/to/HTML-Template/templates',
         },
         
     This is possible because the arguments used by these 2 templating systems are in this case different (C<path> and C<INCLUDE_PATH>). But if 2 templating systems that need to use the same argument are used and if that parameter should have a different value for each one, than it won't be possible to share all the parameters from C<template_args>.
         
     In that case, we could add a new element in the arrayref by specifying the C<template_args> hashref separately for each template:
         
 plaintext => ['template.tt', {INCLUDE_PATH => '/path/to/TT/templates'}, ':TT'],
     htmltext => ['template.tmpl', {path => '/path/to/HT/templates'}, ':HTML::Template'],
     attachment => ['template.tt', 'file.html', 'text/html', {INCLUDE_PATH => '/another/dir'}, ':TT'],

    As you have seen, the "template_args" hashref for each template is added
    as a penultimate element of the arrayref and it can contain the same
    elements as the main "template_args" parameter.

    The variables from the "template_args" hashref overwrite the variables
    defined in the main "template_args" hashref if it is used.

    If more templates are used for creating an email message, possibly using
    more templating systems, all of the templates get the variables
    specified in the "template_vars" hashref.

    However, if 2 or more templates use a value with the same name, but that
    variable should have different values in different templates, you can
    also add a "template_vars" hashref for each template, and overwrite the
    variables specified in the main "template_vars" hashref.

    This "template_vars" hashref which is specified for each template is
    added in the arrayref before the "template_args" hashref. If you need to
    add just a local "template_vars" hashref but not a "template_args" one,
    you need to use an empty hashref - {} in place of the "template_args"
    hashref, like:

     plaintext => [
      'template.tt',
      {name => 'Your Name', age => 20},
      {INCLUDE_PATH => '/path/to/TT/templates'},
      ':TT'
     ],

     htmltext => [
      'template.tmpl',
      {name => 'Another name', address => '...'},
      {},
      ':HTML::Template'
     ],

     attachment => [
      'template.tt',
      'file.html',
      'text/html',
      {name => 'Something Else'},
      {INCLUDE_PATH => '/another/dir'},
      ':TT'
     ],

Using the module
    After using the "send()" function, the "To:", "CC:" and "BCC:" fields
    are cleared from the Mail::Builder::Simple object, so you can use the
    same object to send the same email to other recipients.

    Here is an example:

     my $mail = Mail::Builder::Simple->new(from => 'me@myhost.com');

     $mail->send(
      to => 'you@host.com',
      subject => 'The subject',
      plaintext => 'The body of the message',
     );

     $mail->send(to => 'he@host2.com');
     $mail->send(to => 'she@host3.com');

    The last 2 lines sent the message previously created. If you want to
    create an entirely new message, you should use the method "new()" again.

BUGS
    If you find some, please tell me.

SEE ALSO
    Mail::Builder, Email::Send, Template, HTML::Template, Config::Any

AUTHOR
    Octavian Rasnita <orasnita@gmail.com>

COPYRIGHT
    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.