The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Activator-0.10
River stage zero No dependents
++
/ Activator::Emailer

NAME

Activator::Emailer

SYNOPSIS

  use Activator::Emailer;
  my $tt_vars = { pkg => 'Activator::Emailer' };
  my $mailer = Activator::Emailer->new(
     From        => 'no-reply@test.com',
     To          => 'person@test.com',
     Cc          => [ qw( 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 );

See CONFIGURATION for how to use Activator::Registry to simplify the above usage to:

  use Activator::Emailer;
  my $tt_vars = { pkg => 'Activator::Emailer' };
  my $mailer = Activator::Emailer->new(
     To          => 'person@test.com',
     Cc          => [ qw( other@test.com other2@test.com ) ],
     Subject     => 'Test Subject',
     html_body   => '/path/to/html_body.tt',
  );
  $mailer->attach( Type        => 'application/pdf',
                   Path        => 'path/to/doc.pdf',
                   Filename    => 'invoice.pdf',
                   Disposition => 'attachment' );
  $mailer->send( $tt_vars );
  $mailer->set_html_body( "Hello again. This is <b>[% pkg %]</b>\n" );
  $tt_vars->{pkg} = 'Other::Package';
  $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.

CONFIGURATION

You can utilize Activator::Registry to simplify creation of emails:

  'Activator::Registry':
    'Activator::Emailer':
      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>
      From: default@domain.com
      html_header: /fully/qualified/path/to/header/tt/template
      html_footer: relative/path/to/footer/tt/template
      email_wrap:  /path/to/email/wrapper/template
      tt_options:
        INCLUDE_PATH: /path/to/tt/templates

TEMPLATES SETUP

You must create 4 template for emails to work. Each template has a variable Activator_Emailer_format available so you can do format specific template blocks. Note that it is suggested that you utilize the TT chomping close tag (-%]) to maintain format.

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>

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 -%]

This is the most basic footer, but you can add as much HTML as you like:

  </body>
  </html>

email_wrap

Copy this verbatim:

  [% 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 -%]

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 addresses

  • The 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> class

  • The following are used with Template::Toolkit

     * tt_include_path - The INCLUDE_PATH for template toolkit. Useful
                     for reusing project templates within an email

  • The 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 )

attach( %args )

    Attach an item to this email. When send() is called, %args is just passed through to the MIME::Lite attach function.

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 Nassar ( karim.nassar@acm.org )

License

The Activator::Emailer module is Copyright (c) 2007 Karim 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.