NAME
Activator::Emailer - Send emails from anywhere within a project in the same way using role-based configuration.
SYNOPSIS
Configure defaults with Activator::Registry configuration (See CONFIGURATION), then:
use Activator::Emailer;
my $tt_vars = { data => 'any data your template needs',
other_data => $my_data,
};
my $mailer = Activator::Emailer->new(
To => 'person@test.com',
Cc => 'other@test.com, other2@test.com'
Subject => 'Test Subject',
);
$mailer->send( $tt_vars );Reuse the mailer object to send another mail to someone else using a different body template, plus an attachment:
$mailer->set_cc( '' );
$mailer->set_to( 'someone_else@other-domain.com' );
$mailer->set_html_body( '/path/to/html_body.tt' );
$tt_vars = $my_alternate_data_hashref;
$mailer->attach( Type => 'application/pdf',
Path => 'path/to/doc.pdf',
Filename => 'doc.pdf',
Disposition => 'attachment' );
$mailer->send( $tt_vars );DESCRIPTION
Activator::Emailer is a simple wrapper to Mime::Lite, Template::Toolkit and Email::Send that uses your project's Activator::Registry to facilitate easy sending of multipart text/html email from any module in your project. Emailer can talk to any MTAs that Email::Send can.
Full Example
use Activator::Emailer;
my $tt_vars = { data => $my_data,
other_data => 'any data your template needs'
};
my $mailer = Activator::Emailer->new(
From => 'no-reply@test.com',
To => 'person@test.com',
Cc => 'other@test.com, other2@test.com'
Subject => 'Test Subject',
html_header => '/path/to/html_header.tt',
html_body => '/path/to/html_body.tt',
html_footer => '/path/to/html_footer.tt',
email_wrap => '/path/to/email/wrapper/template',
mailer_type => 'Gmail',
mailer_args => [ username => 'user@gmail.com',
password => '123456'
],
);
$mailer->attach( Type => 'application/pdf',
Path => 'path/to/doc.pdf',
Filename => 'invoice.pdf',
Disposition => 'attachment'
$mailer->send( $tt_vars );The next section shows how to simplify this.
CONFIGURATION
As is seen in the previous section, a lot of information is needed to send an email. Fortunately, most of the information is reusable. You can utilize Activator::Registry to simplify creation of emails:
'Activator::Registry':
'Activator::Emailer':
From: noreply@domain.com
mailer_type: Gmail # any of the send methods Email::Send supports
mailer_args: # any of the args required by your Email::Send::<TYPE>
- username: <username>
- password: <password>
html_header: /fully/qualified/path/to/header/tt/template
html_footer: relative/path/to/footer/tt/template
html_body: relative/path/to/body/tt/template
email_wrap: /path/to/email/wrapper/template
tt_options:
INCLUDE_PATH: /path/to/tt/templatesIn the simplist case, you can now send as such:
my $mailer = Activator::Emailer->new(
To => 'person@test.com',
Subject => 'Test Subject',
);
$mailer->send( { data => $my_data } );TEMPLATES SETUP
You must create 4 template for emails to work. Each template has a variable Activator_Emailer_format available so you can do HTML or text specific template blocks. Note that it is suggested that you utilize the TT chomping close tag (-%]) to maintain format.
File 1: html_header
This is the most basic header, but you can add as much HTML as you like, including limited style and script tags:
<html>
<body>File 2: html_body
Put whatever html you like in this section.
<h1>Body</h1>
<p>This is only an example</p>
[% IF Activator_Emailer_format == 'text' -%]
========================================
[% ELSE -%]
<hr>
[% END -%]File 3: html_footer
This is the most basic footer, but you can add as much HTML as you like:
</body>
</html>File 4: email_wrap.tt
Copy this verbatim, trim the leading space:
[% USE HTML.Strip -%]
[% BLOCK html_header -%]
[% INCLUDE html_header %]
[% END -%]
[% BLOCK html_footer %]
[% INCLUDE html_footer %]
[% END -%]
[% BLOCK body -%]
[% INCLUDE html_body %]
[% END -%]
[% IF format == 'text' -%]
[% FILTER html_strip emit_spaces = 0 -%]
[% INCLUDE body %]
[% END -%]
[% ELSE -%]
[% INCLUDE html_header -%]
[% INCLUDE body %]
[% INCLUDE html_footer -%]
[% END -%]Note that you can put the files anywhere. See CONFIGURATION for more details.
METHODS
new( %args )
Create an Activator::Emailer object. Valid %args are described below.
The following are sent directly to MIME::Lite, and likewise injected directly into the mail header ( hence the capitalization )
* From - A single email address * To - A single email address * Subject - A string * Cc - A string consisting of a comma separated list of email addressesThe following are used for sending with Email::Send:
* mailer_type - Any valid Email::Send subclass * mailer_args - Any args to pass to the <mailer_type> classThe following are used with Template::Toolkit
* tt_include_path - The INCLUDE_PATH for template toolkit. Useful for reusing project templates within an emailThe following are custom to
Activator::Emailer:* html_header - A template file or string to use for the top of the HTML portion of the email * html_footer - A template file or string to use for the bottom of the HTML portion of the email * html_body - A template file or string to use for the html portion. of the email Also, this will be stripped of all HTML tags ( using HTML::Strip ) and used for the body of the text portion of the email.
send( $tt_vars )
Send the email using $tt_vars for the Template::Toolkit process method.
attach( %args )
Attach an item to this email. When send() is called, %args is just passed through to the MIME::Lite attach function.
valid_email ( $email )
Sanity check on the email address. Throws exception on failure.
setters
Each value that can be passed to new() can be modified by calling set_<VALUE>, where value is lowercased.
See Also
Activator::Registry, Activator::Exception, MIME::Lite, Email::Send, Template::Toolkit, Exception::Class::TryCatch, Class::StrongSingleton
AUTHOR
Karim A. Nassar ( karim.nassar@acm.org )
License
The Activator::Emailer module is Copyright (c) 2007 Karim A. Nassar.
You may distribute under the terms of either the GNU General Public License or the Artistic License, or as specified in the Perl README file.