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:

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

If the SMTP server listens to a non-standard port (for example the port 28 instead of 25), you can specify that port after the address or IP of the SMTP server:

 Host => 'smtp.host.com:28',

If you want to send email using an SMTP server that uses SSL, for example send an email with Gmail, use:

 mail_client => {
  mailer => 'SMTP',
  mailer_args => [
   Host => 'smtp.gmail.com:465',
   username => 'the_user',
   password => 'the_password',
   ssl => 1,
  ],
 },

If you install Email::Send::Gmail, you can do this by using just:

 mail_client => {
  mailer => 'Gmail',
  mailer_args => [
   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.

The variables from template_args and template_vars should be defined before using them in a template. So for example if you want to send a message to more addressees and want to send template_vars to the send() method, you also need to send the template's parameters to send() method, because if you define the template earlier, in the new() method, the template won't see the template_vars.

Examples:

Don't do something like this:

  my $mail = Mail::Builder::Simple->new(
    from => 'my@host.com',
    subject => 'The subject',
    htmltext => ['template.tt', ':TT'],
  );
          
  $mail->send(
    to => 'one@host.com',
    template_vars => {name => 'Foo', age => 33},
  );

  $mail->send(
    to => 'two@host2.com',
    template_vars => {name => 'Bar', age => 28},
  );

But do it like this:

  my $mail = Mail::Builder::Simple->new(
    from => 'my@host.com',
    subject => 'The subject',
  );
          
  $mail->send(
    to => 'one@host.com',
    htmltext => ['template.tt', ':TT'],
    template_vars => {name => 'Foo', age => 33},
  );

  $mail->send(
    to => 'two@host2.com',
    htmltext => ['template.tt', ':TT'],
    template_vars => {name => 'Bar', age => 28},
  );

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.

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.

To install Mail::Builder::Simple, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Mail::Builder::Simple

CPAN shell

perl -MCPAN -e shell
install Mail::Builder::Simple

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

Functions

Parameters

mail_client

template_args

template_vars

email message fields

config_file

other email message headers

Using the email message fields

to, cc, bcc

from

subject

plaintext, htmltext

attachments

images

Using templates

Types of templates

Advanced use of templates

Using the module

BUGS

SEE ALSO

AUTHOR

COPYRIGHT

Module Install Instructions